<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>MochiAd Documentation</title>
    <link media="screen" href="css/screen.css" type="text/css" rel="stylesheet">
    <!--[if IE]>
        <link rel="stylesheet" type="text/css" href="css/ie.css" media="screen" />
    <![endif]-->
</head>
<body id="help" class="docs dev">
    <div id="page">
        <div id="content">
                    <!--! TOC -->
                    <div id="toc">
                        <h1><a name="toc"></a>Table of Contents</h1>
                        <ol>
                            <li>
                                <h2><a href="#MochiEvents" title="Analytics API Documentation">Analytics API Documentation</a></h2>
                                <ol>
                                    <li><a href="#tracking_ov" title="Overview">1.1 Overview</a></li>
                                    <li><a href="#tracking_pre" title="Prerequisites">1.2 Prerequisites</a></li>
                                    <li><a href="#tracking_services" title="Connecting to MochiServices">1.3 Connecting to MochiServices</a></li>
                                    <li><a href="#tracking_events" title="Tracking events">1.4 Tracking Custom Events</a></li>
                                    <li><a href="#tracking_api" title="Tracking API">1.5 Tracking API</a></li>
                                </ol>
                            </li>
                            <li>
                                <h2><a href="#MochiSocial" title="Social API Documentation">Social API Documentation</a></h2>
                                <ol>
                                    <li><a href="#social_ov" title="Overview">1.1 Overview</a></li>
                                    <li><a href="#social_pre" title="Prerequisites">1.2 Prerequisites</a></li>
                                    <li><a href="#social_services" title="Connecting to MochiServices">1.3 Connecting to MochiServices</a></li>
                                    <li><a href="#social_login" title="Showing the Universal User Login Widget">1.4 Showing the Universal User Login Widget</a></li>
                                    <li><a href="#social_event" title="Listening to Events">1.5 Listening to Events</a></li>
                                    <li><a href="#social_userproperties" title="Saving persistent user properties">1.6 Saving persistent user properties.</a></li>
                                    <li><a href="#social_api" title="API">1.7 API</a></li>
                                    <li><a href="#social_events" title="Event definitions">1.8 Event definitions</a></li>
                                    <li><a href="#social_mochiuserdata" title="Universal Data Storage">1.9 Universal Data Storage</a></li>
                                </ol>
                            </li>
                            <li>
                                <h2><a href="#MochiCoins" title="Coins API Documentation">Coins API Documentation</a></h2>
                                <ol>
                                    <li><a href="#coins_ov" title="Overview">1.1 Overview</a></li>
                                    <li><a href="#coins_pre" title="Prerequisites">1.2 Prerequisites</a></li>
                                    <li><a href="#coins_services" title="Connecting to MochiServices">1.3 Connecting to MochiServices</a></li>
                                    <li><a href="#coins_event" title="Listening to Events">1.4 Listening to Events</a></li>
                                    <li><a href="#coins_store" title="Showing the store">1.5 Showing the store</a></li>
                                    <li><a href="#coins_item" title="Showing a single item">1.6 Showing a single item</a></li>
                                    <li><a href="#coins_video" title="Prerequisites">1.7 Showing a demonstration video</a></li>
                                    <li><a href="#coins_api" title="API">1.8 API</a></li>
                                    <li><a href="#coins_events" title="Event definitions">1.9 Event definitions</a></li>
                                    <li><a href="#coins_mochiinventory" title="Consumables and In-Game Currency Support">1.10 Consumables and In-Game Currency Support API</a></li>
                                    <li><a href="#coins_sandbox" title="Sandbox Mode">2.0 Sandbox Mode</a></li>
                                    <li><a href="#coins_server" title="Server Validation">3.0 Server Validation</a></li>

                                </ol>
                            </li>
                            <li>
                                <!--! MOCHIADS -->
                                <h2><a href="#MochiAds" title="Ads API Documentation">Ads API</a></h2>
                                <ol>
                                    <li><a href="#Prerequisites:" title="Prerequisites">1.1 Prerequisites</a></li>
                                    <li><a href="#The_MochiAds_Codes:" title="The Mochi Ads API Ad Codes">1.2 The Mochi API Ad Codes</a>
                                        <ol>
                                            <li><a href="#Include_File_Installation:" title="Include Folder Installation">Include Folder Installation</a></li>
                                            <li><a href="#Adding_the_In-game_Code:" title="Adding the In-game Code">Adding the In-game Code</a></li>
                                            <li><a href="#Pregame_Code:" title="Using the Pre Game Ad">Pre-game Ad</a></li>
                                            <li><a href="#Interlevel_Code:" title="Using the Interlevel Ad">Interlevel Ad</a></li>
                                            <li><a href="#Clickaway_Code:" title="Using the Click-away Ad">Click-away Ad</a></li>
                                        </ol>
                                    </li>
                                    <li><a href="#Customizing_Your_Ad" title="Customizing Your Ad">1.3 Customizing Your Ad</a></li>
                                    <li><a href="#Changing_Ad_Behaviors" title="Changing Ad Behaviors">1.4 Changing Ad Behaviors</a></li>
                                    <li><a href="#MTASC_and_MXMLC" title="MTASC and MXMLC">1.5 MTASC and MXMLC</a></li>
                                    <li><a href="#Flex" title="Adobe Flex">1.6 Adobe Flex</a></li>
                                    <li><a href="#AS3_Preloader" title="AS3 Preloader">1.7 ActionScript 3.0 Preloader</a></li>
                                    <li><a href="#FlashDevelop" title="AS3 Preloader">1.8 Flash Develop</a></li>
                                    <li><a href="#More_Resources" title="More Resources">1.9 More Resources</a></li>
                                </ol>
                            </li>
                            <li>
                                <!--! MOCHISERVICES -->
                                <h2><a href="#MochiServices" title="Scores API Documentation">Scores API</a></h2>
                                <ol>
                                    <li>
                                        <!--! MochiServices -->
                                        <h3><a href="#serv_ov" title="MochiServices Documentation">1.0 Overview</a></h3>
                                        <ol>
                                            <li><a href="#serv_ov" title="Prerequisites">1.1 Overview</a></li>
                                            <li><a href="#serv_pre" title="Prerequisites">1.2 Prerequisites</a></li>
                                            <li><a href="#serv_api" title="Prerequisites">1.3 Connecting to MochiServices</a></li>
                                        </ol>
                                    </li>
                                    <li>
                                        <!--! LEADERBOARDS -->
                                        <h3><a href="#MochiScores" title="Scores Documentation">2.0 Scores</a></h3>
                                        <ol>
                                            <li><a href="#score_ov" title="Prerequisites">2.1 Overview</a></li>
                                            <li><a href="#score_pre" title="Prerequisites">2.2 Prerequisites</a></li>
                                            <li><a href="#Displaying_the_Leaderboard_Widget" title="Displaying the Scores Widget">2.3 Displaying the Leaderboard Widget</a></li>
                                            <li><a href="#Saving_Your_Board_ID" title="Saving Your Board ID">2.4 Saving Your Board ID</a></li>
                                            <li><a href="#Other_Leaderboard_Options" title="Other Scores Options">2.5 Other Scores Options</a></li>
                                            <li><a href="#The_MochiScores_API" title="The Mochi Scores API">2.6 Scores API Reference</a></li>
                                            <li><a href="#Error_Handling">2.7 Error Handling</a></li>
                                            <li><a href="#Scores_Data_Format" title="Scores Data Format">2.8 Custom Scores and Scores Data</a></li>
                                        </ol>
                                    </li>
                                    <li>
                                        <!--! LEADERBOARDS -->
                                        <h3><a href="#MochiDigits" title="MochiDigits Documentation">3.0 MochiDigits</a></h3>
                                        <ol>
                                            <li><a href="#digits_ov" title="Prerequisites">3.1 Overview</a></li>
                                            <li><a href="#digits_pre" title="Prerequisites">3.2 Prerequisites</a></li>
                                            <li><a href="#digits_use" title="Prerequisites">3.3 Usage</a></li>
                                        </ol>
                                    </li>
                                </ol>


                                <h2><a href="#LinkTracking" title="Link Tracking Documentation">Link Tracking API</a></h2>

                                <ol>
                                    <!--! LINK TRACKING -->
                                    <li><a href="#link_ov" title="Prerequisites">1.1 Overview</a></li>
                                    <li><a href="#link_pre" title="Prerequisites">1.2 Prerequisites</a></li>
                                    <li><a href="#link_api" title="Prerequisites">1.3 API Reference</a></li>
                                </ol>
                            </li>
                        </ol>
                        <div class="clear"></div>
                    </div>
                    
                    <!--! MochiEvents -->
                    <div class="section_1">
                        <a name="MochiEvents"></a>
                        <h1>Analytics API Documentation</h1>

                        <div class="section_2">
                            <a name="tracking_ov"></a>
                            <h2>1.1 Overview</h2>
                            <p>
                                The Analytics API provides developers with a means of tracking user game information.  This includes session durations, how long the average 
                                player spends in an average round of play, as well as tracking other events such as item pick-ups, reaching waypoints.
                            </p>
                        </div>

                        <div class="section_2">
                            <a name="tracking_pre"></a>
                            <h2>1.2 Prerequisites</h2>
                            <p>
                                MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                            </p>

                            <h4>Installing the Mochi Analytics Tracking API</h4>
                            <ol>
                                <li>Download and unzip the latest MochiAPI.</li>
                                <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                            </ol>

                            <div class="download">
                                <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                            </div>
                        </div>
                        
                        <div class="section_2">
                            <a name="tracking_services"></a>
                            <h2>1.3 Connecting to MochiServices</h2>

                            <div class="method">
                                <h3>connect</h3>
                                <div class="function">
                                    <div class="signature">
                                        connect(id:String, clip:Object, onError:Function):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Retrieves and initializes the MochiServices.swf from Mochi servers. Any API calls executed prior to the complete download and initialization
                                            of the MochiServices.swf are queued and will be executed once the API is available
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>id</strong>:String</dt>
                                            <dd>Mochi game ID</dd>
                                            <dt><strong>clip</strong>:Object</dt>
                                            <dd>the MovieClip or Sprite in which to load the API (optional for all but AS3, defaults to _root).  In as3 the clip must be dynamic.</dd>
                                            <dt><strong>onError</strong>:Function</dt>
                                            <dd>
                                                This method will be invoked if MochiServices cannot connect to the server or any IO errors occur in any other API calls.
                                                onError handlers will receive status codes that describe the error.  The possible errors are:
                                                <ul>
                                                    <li>NotConnected &mdash; Services were unable to connect or attach to a clip in the current movie.</li>
                                                    <li>IOError &mdash; Services has connected but cannot transfer data to and from the server.</li>
                                                </ul>
                                            </dd>
                                        </dl>
                                    </div>




                                    <div class="example">
                                        <h4>AS3 Example:</h4>

<blockquote class="code"><pre>
mochi.as3.MochiServices.connect("xxx", root, onConnectError);  // use mochi.as2.MochiServices.connect for AS2 API

public function onConnectError(status:String):void {
<span class="comment">// handle error here...</span>
}
</pre></blockquote>

                                        <p>&hellip; where &lsquo;xxx&rsquo; is your Mochi game ID, in quotes. Test your movie, and you should see the following text in your output panel:</p>

                                        <blockquote class="code trace">
                                            MochiServices Connecting&hellip;<br />
                                            Waiting for Mochi services to connect&hellip;<br />
                                            connected!
                                        </blockquote>

                                        <p>
                                            If you see the text above, then that means you have the "mochi" folder in the correct location, and have
                                            supplied MochiServices the correct Mochi game ID.  Keep in mind that you want to connect to MochiServices as early as
                                            possible in your game, and before you make any other API calls.  You only need to make this call once in the
                                            beginning of your game.
                                        </p>

                                        <h3>AS3 Requirement - The <em>clip</em> parameter</h3>
                                        <p>
                                            In ActionScript 3, the root of the Stage cannot be accessed globally.  If a Sprite or MovieClip does not have access to the root
                                            or to another Display Container that has been added to the display list, then it can not be shown visually on the screen.  For
                                            this reason, you must supply either the root of your stage or a reference to a Sprite or MovieClip that is a child of the stage
                                            to the clip parameter when you call MochiServices.connect.  Please note the clip passed must also be dynamic.
                                        </p>

                                    </div>
                                </div>
                            </div>
                        </div>

                        <div class="section_2">
                            <a name="tracking_events"></a>
                            <h2>1.4 Analytics API</h2>
                            <p>
                                The Analytics API really consists of only 3 basic calls.  These calls allow our system to determine the duration the average users spends 
                                in your game in a single session, the time the player spends during actual gameplay, as well as tracking explicit events you define.  
                                Session duration tracking occurs automatically with most games using MochiServices.com and requires no intervention by the developer.  
                                Tracking game play and custom events requires new function calls to be added to your game.
                            </p>

                            <p>
                                <h4>Tracking a gameplay round</h4>
                                Tracking gameplay time consists of two calls.  These calls are startPlay and endPlay.  The combination of the two lets our servers derive the total amount of 
                                time a user spends playing your game.  It should be noted that there can only be one active round, so you will not be able to track multiple durations at the same time.
                            </p>

                            <p>
                            <h4>AS3 Example:</h4>

                    <blockquote class="code"><pre>
mochi.as3.MochiEvents.startPlay('easy');
// ... level actions happen
mochi.as3.MochiEvents.endPlay();
                    </pre></blockquote>
                                
                            </p>

                            <p>
                                <h4>Tracking custom events</h4>
                                Aside from tracking gameplay durations, we also offer support for tracking other in game events.  These events do not imply a duration, so they can be 
                                used for tracking things like in world accomplishments as well as flagging important milestones for the developers.  This could be used for tooling the 
                                difficulty of specific stages or simply tracking stats.
                            </p>

                            <p>
                            <h4>AS3 Example:</h4>

                    <blockquote class="code"><pre>
mochi.as3.MochiEvents.trackEvent('level gained',7);
                    </pre></blockquote>

                            </p>
                        </div>
                        
                        <div class="section_2">
                            <a name="tracking_api"></a>
                            <h2>1.5 API Reference </h2>

                            <div class="method">
                                <h3>startPlay</h3>
                                <div class="function">
                                    <div class="signature">
                                        startPlay(tag:String):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Track the start of gameplay.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>tag</strong>:String</dt>
                                            <dd>'tag' associated with gameplay (eg: 'hard')</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>
<blockquote class="code"><pre>MochiEvents.startPlay('hard');</pre></blockquote>
                                    </div>
                                </div>
                            </div>
                            
                            <div class="method">
                                <h3>endPlay</h3>
                                <div class="function">
                                    <div class="signature">
                                        endPlay():void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Flag gameplay as finished.
                                        </p>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>
<blockquote class="code"><pre>
MochiEvents.endPlay();</pre></blockquote>
                                    </div>
                                </div>
                            </div>
                            
                            <div class="method">
                                <h3>trackEvent</h3>
                                <div class="function">
                                    <div class="signature">
                                        trackEvent( tag:String, value:* ):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Track miscellaneous associative event
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>tag</strong>:String</dt>
                                            <dd>event type 'tag' name</dd>
                                        </dl>
                                        <dl>
                                            <dt><strong>value</strong>:*</dt> <strong>(optional)</strong>
                                            <dd>value associated with event type</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>
<blockquote class="code"><pre>MochiEvents.trackEvent( 'getGrenades', 5 );</pre></blockquote>
                                    </div>
                                </div>
                            </div>
                            
                        </div>
                    </div>

                                        <!--! MochiSocial -->
                                        <div class="section_1">
                                            <a name="MochiSocial"></a>
                                            <h1>MochiSocial API Documentation</h1>

                                            <div class="section_2">
                                                <a name="social_ov"></a>
                                                <h2>1.1 Overview</h2>
                                                <p>
                                                    The Mochi Social API provides developers with a method for establishing a login system through out their games, as well as tracking user progress remotely.  This feature was once part of the MochiCoins API, but has since been detached into it's own API.
                                                </p>
                                            </div>

                                            <div class="section_2">
                                                <a name="social_pre"></a>
                                                <h2>1.2 Prerequisites</h2>
                                                <p>
                                                    MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                                                </p>

                                                <h4>Installing the Mochi Social API</h4>
                                                <ol>
                                                    <li>Download and unzip the latest MochiAPI.</li>
                                                    <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                                                </ol>

                                                <div class="download">
                                                    <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                                                </div>

                                            </div>

                                            <div class="section_2">
                                                <a name="social_services"></a>
                                                <h2>1.3 Connecting to MochiServices</h2>

                                                <div class="method">
                                                    <h3>connect</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            connect(id:String, clip:Object, onError:Function):void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Retrieves and initializes the MochiServices.swf from Mochi servers. Any API calls executed prior to the complete download and initialization
                                                                of the MochiServices.swf are queued and will be executed once the API is available
                                                            </p>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Parameters:</h4>
                                                            <dl>
                                                                <dt><strong>id</strong>:String</dt>
                                                                <dd>Mochi game ID</dd>
                                                                <dt><strong>clip</strong>:Object</dt>
                                                                <dd>the MovieClip or Sprite in which to load the API (optional for all but AS3, defaults to _root).  In as3 the clip must be dynamic.</dd>
                                                                <dt><strong>onError</strong>:Function</dt>
                                                                <dd>
                                                                    This method will be invoked if MochiServices cannot connect to the server or any IO errors occur in any other API calls.
                                                                    onError handlers will receive status codes that describe the error.  The possible errors are:
                                                                    <ul>
                                                                        <li>NotConnected &mdash; Services were unable to connect or attach to a clip in the current movie.</li>
                                                                        <li>IOError &mdash; Services has connected but cannot transfer data to and from the server.</li>
                                                                    </ul>
                                                                </dd>
                                                            </dl>
                                                        </div>




                                                        <div class="example">
                                                            <h4>AS3 Example:</h4>

                    <blockquote class="code"><pre>
mochi.as3.MochiServices.connect("xxx", root, onConnectError);  // use mochi.as2.MochiServices.connect for AS2 API

public function onConnectError(status:String):void {
    <span class="comment">// handle error here...</span>
}
                    </pre></blockquote>

                                                            <p>&hellip; where &lsquo;xxx&rsquo; is your Mochi game ID, in quotes. Test your movie, and you should see the following text in your output panel:</p>

                                                            <blockquote class="code trace">
                                                                MochiServices Connecting&hellip;<br />
                                                                Waiting for Mochi services to connect&hellip;<br />
                                                                connected!
                                                            </blockquote>

                                                            <p>
                                                                If you see the text above, then that means you have the "mochi" folder in the correct location, and have
                                                                supplied MochiServices the correct Mochi game ID.  Keep in mind that you want to connect to MochiServices as early as
                                                                possible in your game, and before you make any other API calls.  You only need to make this call once in the
                                                                beginning of your game.
                                                            </p>

                                                            <h3>AS3 Requirement - The <em>clip</em> parameter</h3>
                                                            <p>
                                                                In ActionScript 3, the root of the Stage cannot be accessed globally.  If a Sprite or MovieClip does not have access to the root
                                                                or to another Display Container that has been added to the display list, then it can not be shown visually on the screen.  For
                                                                this reason, you must supply either the root of your stage or a reference to a Sprite or MovieClip that is a child of the stage
                                                                to the clip parameter when you call MochiServices.connect.  Please note the clip passed must also be dynamic.
                                                            </p>

                                                        </div>
                                                    </div>
                                                </div>
                                            </div>

                                            <div class="section_2">
                                                <a name="social_login"></a>
                                                <h2>1.4 Showing the Universal User Login Widget.</h2>
                                                <p>
                                                    The Login Widget allows the player to register or login and gives them access to their profile, items, coins and user specific data.   If the player has previously logged in, the widget will show their profile picture, items, and coins.  The Login Widget is 200x25 in size, and will automatically place itself on the lower right corner of your stage.  We recommend this placement for consistency between all games, however you may pass in a custom position for your specific design.
                                                </p>
                                                <p class="codetext">import mochi.as3.*;</p>
                                                <p class="codetext">MochiSocial.showLoginWidget();   // You can also pass a x,y - MochiSocial.showLoginWidget({x:330, y:360})</p>
                                                <p>You can hide the Login Widget with the code below.   The widget will still be loaded to keep state but won't be visible.</p>
                                                <p class="codetext">MochiSocial.hideLoginWidget();</p>
                                            </div>

                                            <div class="section_2">
                                                <a name="social_event"></a>
                                                <h2>1.5 Listening to Events.</h2>
                                                <p>
                                                    Once a player has logged in, you will get a LOGGED_IN event.   If the player previously logged in and has a valid session, this may happen quickly after the MochiServices.connect() call, so listeners should be enabled for these events before your MochiServices.connect() call

                                                </p>
                                                <p class="codetext">import mochi.as3.*; // import mochi.as2.* if using the AS2 API</p>

                        <blockquote class="code"><pre>
MochiSocial.addEventListener(MochiSocial.ERROR, handleError);
MochiSocial.addEventListener(MochiSocial.LOGGED_IN, loggedIn);

MochiServices.connect("xxx", root, onError);

public function loggedIn(event:Object):void {
    // receive {name: name, uid: uid, profileImgURL: profileImgURL, hasCoins: True, userProperties: { hitPoints: 120 }}
    trace("Hello " + event.name);
}
                        </pre></blockquote>

                                                <p>
                                                    It should be noted that the parameter dispatched with an event is an Object, and not a decedent of the Event
                                                    class. While Objects behave in a similar fashion as an Event object, they do not contain the same parameters
                                                    and properties as a built-in AS3 Event.  Likewise, you will not be able to use instanceof, is, as and typeof
                                                    to determine what kind of event has been passed.
                                                </p>
                                            </div>

                                                                <div class="section_2">
                                                                    <a name="social_userproperties"></a>
                                                                    <h2>1.6 Saving persistent player properties.</h2>
                                                                    <p>
                                                                    The MochiSocial API will allow you to save persistent player properties.  This can be used to save any custom player state that can be retrieved on subsequent gameplays.  As an example, you may wish to save the state of health, experience, or the number of levels unlocked for the player which can provide a more continuous game play experience when the user returns to the game at a later time.  The example below will save the key value pairs specified for the logged in player.   Only values of types Number, String, Boolean, and Array can be saved. There is currently a 4KB limit (total serialized size) per user per game that can be saved.
                                                                    </p>
                                                                    <p class="codetext">MochiSocial.saveUserProperties({ hitPoints: 120, levelsFinished: [1, 2, 4, 6] });</p>
                                                                    The above call will overwrite the previous properties Object that may have existed for the player.  On subsequent MochiSocial.LOGGED_IN events, this object will be passed back.
                                                                    <blockquote class="code"><pre>
MochiSocial.addEventListener(MochiSocial.LOGGED_IN, loggedIn);

public function loggedIn(ev:Object):void {
    // receive {name: name, uid: uid, profileImgURL: profileImgURL, hasCoins: True, userProperties: { hitPoints: 120 .. }}
    var userProperties:Object = ev.userProperties
}
                                                                    </pre></blockquote>
                                                                    <p>
                                                                    MochiSocial.PROPERTIES_SAVED event will occur when the properties Object save is successful.   MochiSocial.ERROR of type MochiSocial.PROPERTIES_SIZE or of type MochiSocial.NO_USER will occur when the size of the properties Object is too large, or no user is logged in.  See <a href="#social_events">1.8 Event definitions</a>.
                                                                    </p>
                                                                    <blockquote class="code"><pre>
MochiSocial.addEventListener(MochiSocial.PROPERTIES_SAVED, properties_saved);
MochiSocial.addEventListener(MochiSocial.ERROR, handleError);

public function properties_saved(ev:Object):void {
    trace("Properties Saved!");
}
public function handleError(ev:Object):void {
    switch (ev.type) {
        case MochiSocial.PROPERTIES_SIZE:
            trace("Properties too large.");
            break;
        case MochiSocial.NO_USER:
            trace("No user logged in.");
            break;
    }
}
                                                                    </pre></blockquote>

                                                                </div>

                                            <div class="section_2">
                                                <a name="social_api"></a>
                                                <h2>1.7 API</h2>

                                                <div class="method">
                                                    <h3>showLoginWidget</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            showLoginWidget(options:Object):void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Shows the login widget.
                                                            </p>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Parameters:</h4>
                                                            <dl>
                                                                <dt><strong>x</strong>:Number</dt>
                                                                <dd>x coordinate</dd>
                                                            </dl>
                                                            <dl>
                                                                <dt><strong>y</strong>:Number</dt>
                                                                <dd>y coordinate</dd>
                                                            </dl>
                                                        </div>

                                                        <div class="example">
                                                            <h4>Example:</h4>

                        <blockquote class="code"><pre>
MochiCoins.showLoginWidget({ x:150, y: 150 });</pre></blockquote>

                                                        </div>
                                                    </div>
                                                </div>

                                                <div class="method">
                                                    <h3>hideLoginWidget</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            hideLoginWidget():void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Hides the login widget.
                                                            </p>
                                                        </div>
                                                    </div>
                                                </div>

                                                <div class="method">
                                                    <h3>requestLogin</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            requestLogin():void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Present the user with a modal login screen.
                                                            </p>
                                                        </div>
                                                    </div>
                                                </div>

                                                <div class="method">
                                                    <h3>saveUserProperties</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            saveUserProperties(properties:Object):void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                This method allows you to save custom user state that can be retrieved on subsequent gameplays.
                                                                This is done by passing an Object with key value pairs to this method.   On subsequent MochiSocial.LOGGED_IN
                                                                events, this object will be passed back (See MochiSocial.LOGGED_IN in <a href="#social_events">1.8 Event definitions</a>).
                                                            </p>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Parameters:</h4>
                                                            <dl>
                                                                <dt><strong>properties</strong>:Object</dt>
                                                                <dd>An Object of user defined key value pairs.  Only values of types Number, String, Boolean, Array, and Object will be saved.   There is currently a 4KB limit (total serialized size) per user per game that can be saved.</dd>
                                                            </dl>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Events:</h4>
                                                            <dl>
                                                                <dt><strong>MochiSocial.PROPERTIES_SAVED</strong></dt>
                                                                <dd>User properties successfully saved.  See <a href="#social_events">1.8 Event definitions</a></dd>
                                                            </dl>
                                                        </div>

                                                        <div class="example">
                                                            <h4>Example:</h4>

                                                            <blockquote class="code"><pre>
MochiSocial.saveUserProperties({ hitPoints: 120 });</pre></blockquote>

                                                        </div>

                                                    </div>
                                                </div>

                                            </div>

                                            <div class="section_2">
                                                <a name="social_events"></a>
                                                <h2>1.8 Event definitions</h2>
                                                <p>Events as well as any arguments your event handler will receive are listed below</p>

                                                <dl>
                                                    <dt><strong>MochiSocial.LOGGED_IN</strong> {name: "name", uid: unique_identifier, profileImgURL: url_of_player_image, hasCoins: True, userProperties: {hitPoints: 120}, api_token: "***"}</dt>
                                                    <dd>Player logged in.  This events passes an object with the above keys to your event listener.  The userProperties key is a per user per game property bag that you save with the saveUserProperties call. This event will also be sent after calling MochiServices.connect() if the player is already logged in.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.LOGGED_OUT</strong></dt>
                                                    <dd>Player logged out. This event will also be sent after calling MochiServices.connect() if the player is not logged in.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.LOGIN_SHOW</strong></dt>
                                                    <dd>Login widget showing.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.LOGIN_HIDE</strong></dt>
                                                    <dd>Login widget hidden.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.PROFILE_SHOW</strong></dt>
                                                    <dd>Profile/inventory screen showing.  Player viewing profile/inventory.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.PROFILE_HIDE</strong></dt>
                                                    <dd>Profile/inventory screen hidden.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.PROPERTIES_SAVED</strong></dt>
                                                    <dd>User properties successfully saved.  This happens after a call to MochiCoins.saveUserProperties().</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.WIDGET_LOADED</strong></dt>
                                                    <dd>Login / Store SWF loaded.  Use this event to know when the Login widget has been loaded. For example you may wish to display a splash screen until then to prevent a visual delay in the Login widget appearing.   Calling MochiServices.connect() in the Preloader area of your game can also help load the widget prior to when it's needed.</dd>
                                                </dl>

                                                <dl>
                                                    <dt><strong>MochiSocial.ERROR</strong> { type: MochiSocial.IO_ERROR }</dt>
                                                    <dd>An error occurred.  Values for type are listed below:
                                                        <ul>
                                                            <li>MochiSocial.IO_ERROR: There was a network error.</li>
                                                            <li>MochiSocial.PROPERTIES_SIZE: MochiCoins.saveUserProperties() call failed.  The property size is too large.  There is currently a 4KB limit (total serialized size).</li>
                                                            <li>MochiSocial.NO_USER: MochiCoins.saveUserProperties() call failed.  No user is logged in.</li>
                                                        </ul>
                                                    </dd>
                                                </dl>
                                            </div>
                                            <div class="section_2">
                                                <a name="social_mochiuserdata"></a>
                                                <h2>1.9 Universal Data Storage (AS3-only persistence)</h2>
                                                <p>
                                                    Mochi Social API games written in AS3 have a persistence API that goes far beyond
                                                    the limitations of userProperties.
                                                </p>
                                                <p>
                                                    With this API you can store multiple keys per user without any 4kb limit.
                                                    The data is persisted in AMF3 format with compression, so you can efficiently
                                                    store and transmit anything that could be persisted by SharedObject.
                                                </p>
                                                <p>
                                                    This API is only available when a user is logged in. It will fail if you call it
                                                    before the MochiSocial.LOGGED_IN event is received or if you call it after a
                                                    MochiSocial.LOGGED_OUT event occurs.
                                                </p>
                                                <div class="method">
                                                    <h3>get</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            get(key:String, callback:Function):void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Get the data stored at <em>key</em> for this user, will call
                                                                <em>callback(userData)</em> with the result. If there is no
                                                                value stored at <em>key</em>, userData.data will be null.
                                                            </p>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Parameters:</h4>
                                                            <dl>
                                                                <dt><strong>key</strong>:String</dt>
                                                                <dd>The name of the key to retrieve for this user</dd>
                                                            </dl>
                                                            <dl>
                                                                <dt><strong>callback(userData:MochiUserData):void</strong>:Function</dt>
                                                                <dd>The function to be called on success or error.
                                                                    On success, userData.error is null and userData.data is set to the value of this key for the logged-in user.
                                                                    If the key has not been previously set, userData.data will be null.

                                                                    If an error has occurred, userData.error will be a description of the error.</dd>
                                                            </dl>
                                                        </div>

                                                        <div class="example">
                                                            <h4>Example:</h4>

                        <blockquote class="code"><pre>
                        private function loginEvent(event:Object):void {
                            MochiUserData.get("login_count", gotLoginCount);
                        }

                        private function gotLoginCount(userData:MochiUserData):void {
                            if (userData.error) {
                                trace("[ERROR] could not fetch login_count: " + userData.error);
                                return;
                            }
                            var login_count:Number = 0;
                            if (userData.data !== null) {
                                login_count = login_count.data;
                            }
                            trace("This user has logged in " + login_count + " times");

                            MochiUserData.put("login_count", login_count + 1, putLoginCount);
                        }

                        private function putLoginCount(userData:MochiUserData):void {
                            if (userData.error) {
                                trace("[ERROR] could not put login_count: " + userData.error);
                                return;
                            }
                            trace("Successfully updated login_count for user");
                        }
                        </pre></blockquote>

                                                        </div>
                                                    </div>
                                                </div>




                                                <div class="method">
                                                    <h3>put</h3>
                                                    <div class="function">
                                                        <div class="signature">
                                                            put(key:String, value:*, callback:Function):void
                                                        </div>

                                                        <div class="description">
                                                            <h4>Description:</h4>
                                                            <p>
                                                                Store <em>value</em> at <em>key</em> for this user, will call
                                                                <em>callback(userData)</em> to report success or error. If
                                                                the put succeeded, userData.error will be null.
                                                            </p>
                                                        </div>

                                                        <div class="parameters">
                                                            <h4>Parameters:</h4>
                                                            <dl>
                                                                <dt><strong>key</strong>:String</dt>
                                                                <dd>The name of the key to retrieve for this user</dd>
                                                            </dl>
                                                            <dl>
                                                                <dt><strong>value</strong>:*</dt>
                                                                <dd>The value to store at key for this user. Can be anything serializable by <a href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/net/ObjectEncoding.html" target="_blank">AMF3</a> (in other words, anything that you could put in a SharedObject).</dd>
                                                            </dl>
                                                            <dl>
                                                                <dt><strong>callback(userData:MochiUserData):void</strong>:Function</dt>
                                                                <dd>The function to be called on success or error. On success, userData.error is null.
                                                                    If an error has occurred, userData.error will be a description of the error.</dd>
                                                            </dl>
                                                        </div>

                                                        <div class="example">
                                                            <h4>Example:</h4>

                        <blockquote class="code"><pre>
                        private function loginEvent(event:Object):void {
                            MochiUserData.get("login_count", gotLoginCount);
                        }

                        private function gotLoginCount(userData:MochiUserData):void {
                            if (userData.error) {
                                trace("[ERROR] could not fetch login_count: " + userData.error);
                                return;
                            }
                            var login_count:Number = 0;
                            if (userData.data !== null) {
                                login_count = login_count.data;
                            }
                            trace("This user has logged in " + login_count + " times");

                            MochiUserData.put("login_count", login_count + 1, putLoginCount);
                        }

                        private function putLoginCount(userData:MochiUserData):void {
                            if (userData.error) {
                                trace("[ERROR] could not put login_count: " + userData.error);
                                return;
                            }
                            trace("Successfully updated login_count for user");
                        }
                        </pre></blockquote>

                                                        </div>
                                                    </div>
                                                </div>
                                            </div>

                    </div>

                    <!--! MochiCoins -->
                    <div class="section_1">
                        <a name="MochiCoins"></a>
                        <h1>Coins API Documentation</h1>

                        <div class="section_2">
                            <a name="coins_ov"></a>
                            <h2>1.1 Overview</h2>
                            <p>
                                The Mochi Coins API provides an easy way to sell game upgrades like level unlocks, equipment, special weapons and cheats to players.  It also provides secure login and server side persistence of player data to store game state and user data no matter where the game is played.
                            </p>
                        </div>

                        <div class="section_2">
                            <a name="coins_pre"></a>
                            <h2>1.2 Prerequisites</h2>
                            <p>
                                MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                            </p>

                            <h4>Installing the Coins API</h4>
                            <ol>
                                <li>Download and unzip the latest MochiAPI.</li>
                                <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                                <li>Create your store and add items in your Mochi Developer account.</li>
                            </ol>

                            <div class="download">
                                <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                            </div>

                        </div>

                        <div class="section_2">
                            <a name="coins_services"></a>
                            <h2>1.3 Connecting to MochiServices</h2>

                            <div class="method">
                                <h3>connect</h3>
                                <div class="function">
                                    <div class="signature">
                                        connect(id:String, clip:Object, onError:Function):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Retrieves and initializes the MochiServices.swf from Mochi servers. Any API calls executed prior to the complete download and initialization
                                            of the MochiServices.swf are queued and will be executed once the API is available
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>id</strong>:String</dt>
                                            <dd>Mochi game ID</dd>
                                            <dt><strong>clip</strong>:Object</dt>
                                            <dd>the MovieClip or Sprite in which to load the API (optional for all but AS3, defaults to _root).  In as3 the clip must be dynamic.</dd>
                                            <dt><strong>onError</strong>:Function</dt>
                                            <dd>
                                                This method will be invoked if MochiServices cannot connect to the server or any IO errors occur in any other API calls.
                                                onError handlers will receive status codes that describe the error.  The possible errors are:
                                                <ul>
                                                    <li>NotConnected &mdash; Services were unable to connect or attach to a clip in the current movie.</li>
                                                    <li>IOError &mdash; Services has connected but cannot transfer data to and from the server.</li>
                                                </ul>
                                            </dd>
                                        </dl>
                                    </div>




                                    <div class="example">
                                        <h4>AS3 Example:</h4>

<blockquote class="code"><pre>
mochi.as3.MochiServices.connect("xxx", root, onConnectError);  // use mochi.as2.MochiServices.connect for AS2 API

public function onConnectError(status:String):void {
    <span class="comment">// handle error here...</span>
}
</pre></blockquote>

                                        <p>&hellip; where &lsquo;xxx&rsquo; is your Mochi game ID, in quotes. Test your movie, and you should see the following text in your output panel:</p>

                                        <blockquote class="code trace">
                                            MochiServices Connecting&hellip;<br />
                                            Waiting for Mochi services to connect&hellip;<br />
                                            connected!
                                        </blockquote>

                                        <p>
                                            If you see the text above, then that means you have the "mochi" folder in the correct location, and have
                                            supplied MochiServices the correct Mochi game ID.  Keep in mind that you want to connect to MochiServices as early as
                                            possible in your game, and before you make any other API calls.  You only need to make this call once in the
                                            beginning of your game.
                                        </p>

                                        <h3>AS3 Requirement - The <em>clip</em> parameter</h3>
                                        <p>
                                            In ActionScript 3, the root of the Stage cannot be accessed globally.  If a Sprite or MovieClip does not have access to the root
                                            or to another Display Container that has been added to the display list, then it can not be shown visually on the screen.  For
                                            this reason, you must supply either the root of your stage or a reference to a Sprite or MovieClip that is a child of the stage
                                            to the clip parameter when you call MochiServices.connect.  Please note the clip passed must also be dynamic.
                                        </p>

                                    </div>
                                </div>
                            </div>
                        </div>

                        <div class="section_2">
                            <a name="coins_event"></a>
                            <h2>1.4 Listening to Events.</h2>
                            <p>
                                Once a player has logged in, you will get a LOGGED_IN event followed by ITEM_OWNED events for each item the player owns.   If the player previously logged in and has a valid session, this may happen quickly after the MochiServices.connect() call, so listeners should be enabled for these events before your MochiServices.connect() call.   When players purchase an item, the ITEM_NEW event will happen, allowing you to register the item for your game.

                            </p>
                            <p class="codetext">import mochi.as3.*; // import mochi.as2.* if using the AS2 API</p>

    <blockquote class="code"><pre>
    MochiSocial.addEventListener(MochiSocial.ERROR, handleError);
    MochiSocial.addEventListener(MochiSocial.LOGGED_IN, loggedIn);
    MochiCoins.addEventListener(MochiCoins.ITEM_OWNED, registerItem);
    MochiCoins.addEventListener(MochiCoins.ITEM_NEW, newItem);

    MochiServices.connect("xxx", root, onError);

    public function loggedIn(event:Object):void {
        // receive {name: name, uid: uid, profileImgURL: profileImgURL, hasCoins: True, userProperties: { hitPoints: 120 }}
        trace("Hello " + event.name);
    }

    public function registerItem(event:Object):void {
        // receive {id: id, count: count}
        trace("Player owns " + event.count + " of " + event.id);
    }

    public function newItem(event:Object):void {
        // receive {id: id, count: count}
        trace("Player just bought " + event.count + " of " + event.id);
    }
    </pre></blockquote>

                            <p>
                                It should be noted that the parameter dispatched with an event is an Object, and not a decedent of the Event
                                class. While Objects behave in a similar fashion as an Event object, they do not contain the same parameters
                                and properties as a built-in AS3 Event.  Likewise, you will not be able to use instanceof, is, as and typeof
                                to determine what kind of event has been passed.
                            </p>
                        </div>

                        <div class="section_2">
                            <a name="coins_store"></a>
                            <h2>1.5 Showing the store.</h2>
                            <p>
                            Use MochiCoins.showStore() to show your store with two or more items.   You may pass an optional tags array to show a subset of the items in your store that match the tags defined in your items in your Mochi Developer account. The tags array can also have specific itemIds specified as each item is already implicitly tagged with its itemId.   The example below shows all items with the "weapons" tag as well as a specific itemId.  No x,y coordinates are passed as the store should fill the stage.
                            </p>
                            <p class="codetext">MochiCoins.showStore({ tags: ["weapons", "c27d0672bf98ec05"] });</p>
                        </div>

                        <div class="section_2">
                            <a name="coins_item"></a>
                            <h2>1.6 Showing a single item.</h2>
                            <p>
                            Use MochiCoins.showItem() to show a modal dialog offering a single item.  Pass the item identifier listed for your item in your Mochi Developer account. The dialog will center itself on the stage but you may also pass x,y coordinates.
                            </p>
                            <p class="codetext">MochiCoins.showItem({item: "xxx"}); // You can also pass a x,y - MochiCoins.showItem({x:330, y:360, item: "xxx"})</p>
                        </div>

                                            <div class="section_2">
                                                <a name="coins_video"></a>
                                                <h2>1.7 Showing an item demonstration video.</h2>
                                                <p>
                                                Use MochiCoins.showVideo() to show a modal dialog displaying the demonstration video associated with an item.  The call will be ignored if the item ID is invalid, or there is no video associated with the specified item.
                                                </p>
                                                <p class="codetext">MochiCoins.showVideo({item: "xxx"});</p>
                                            </div>

                                            
                        <div class="section_2">
                            <a name="coins_api"></a>
                            <h2>1.8 API</h2>

                            <div class="method">
                                <h3>showStore</h3>
                                <div class="function">
                                    <div class="signature">
                                        showStore(options:Object):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Shows the game store.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>tags</strong>:Array (optional)</dt>
                                            <dd>Array of string group names for filtering</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>

    <blockquote class="code"><pre>
    MochiCoins.showStore({ tags: ["weapons"] });
    </pre></blockquote>

                                    </div>
                                </div>
                            </div>

                            <div class="method">
                                <h3>showItem</h3>
                                <div class="function">
                                    <div class="signature">
                                        showItem(options:Object):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Shows a single item for purchase. The UI will center itself on the stage be default if no custom coordinates are passed.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>x</strong>:Number</dt>
                                            <dd>x coordinate</dd>
                                        </dl>
                                        <dl>
                                            <dt><strong>y</strong>:Number</dt>
                                            <dd>y coordinate</dd>
                                        </dl>
                                        <dl>
                                             <dt><strong>item</strong>:String</dt>
                                             <dd>item id</dd>
                                        </dl>
                                        <dl>
                                             <dt><strong>bought</strong>:Boolean (optional)</dt>
                                             <dd>set to true if you wish to show the single item dialog and force the ui to show the item as being bought by the user.  This can be useful if you sell an item that represents a bundle of other items in your game and wish to prevent players who have already bought that bundle from purchasing this single item.</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>

    <blockquote class="code"><pre>
    MochiCoins.showItem({ x:150, y: 150, item: "xxx" });
    </pre></blockquote>
                                    </div>

                                </div>
                            </div>
                            
                            <div class="method">
                                <h3>showVideo</h3>
                                <div class="function">
                                    <div class="signature">
                                        showVideo(options:Object):void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Shows the demonstration video associated with the specified item ID.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                             <dt><strong>item</strong>:String</dt>
                                             <dd>item id</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>Example:</h4>

    <blockquote class="code"><pre>
    MochiCoins.showVideo({ item: "xxx" });
    </pre></blockquote>
                                    </div>

                                </div>
                            </div>
                                                    
                            <div class="method">
                                <h3>getStoreItems</h3>
                                <div class="function">
                                    <div class="signature">
                                        getStoreItems():void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Get items metadata from the store.  This will fire the MochiCoins.STORE_ITEMS event.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Events:</h4>
                                        <dl>
                                            <dt><strong>MochiCoins.STORE_ITEMS</strong></dt>
                                            <dd>Event with metadata.  See <a href="#coins_events">1.9 Event definitions</a></dd>
                                        </dl>
                                    </div>

                                </div>
                            </div>
                        </div>

                        <div class="section_2">
                            <a name="coins_events"></a>
                            <h2>1.9 Event definitions</h2>
                            <p>Events as well as any arguments your event handler will receive are listed below</p>

                            <dl>
                                <dt><strong>MochiCoins.STORE_SHOW</strong></dt>
                                <dd>Store (single or multiple items) showing.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiCoins.STORE_HIDE</strong></dt>
                                <dd>Store hidden.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiCoins.ITEM_OWNED</strong> {id: item id, count: number owned, tags: [ "powerup", "enhancement" ], properties: { power: 20 }}</dt>
                                <dd>Player owns item.  The values of the tags and properties keys are what you have set your Item Store under your developer account.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiCoins.ITEM_NEW</strong> {id: item id, count: number bought, tags: [ "powerup", "enhancement" ], properties: { power: 20 }}</dt>
                                <dd>Player bought item.  The values of the tags and properties keys are what you have set your Item Store under your developer account.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiCoins.STORE_ITEMS</strong> [ { id: "ab473e7f87129ecb", name: "Super Cannon", desc: "A Super Cannon", imgURL: "http://..", cost: 150, maxNum: 1, tags: [ level-1, powerup] ], properties: { power: 20 } } ]</dt>
                                <dd>Calling MochiCoins.getStoreItems() will trigger this event, passes an array of item meta objects.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiCoins.ERROR</strong> { type: MochiCoins.IO_ERROR }</dt>
                                <dd>An error occurred.  Values for type are listed below:
                                    <ul>
                                        <li>MochiCoins.IO_ERROR: There was a network error.</li>
                                    </ul>
                                </dd>
                            </dl>
                        </div>

                        <div class="section_2">
                            <a name="coins_mochiinventory"></a>

                            <h2>1.10 Consumables and In-Game Currency Support (AS3-only purchase and consumable tracking)</h2>
                            <p>
                                MochiInventory is a layer on top of the Universal Data Storage, created for
                                tracking purchases, consumables and game-specific currency.
                            </p>

                            <p>
                                The API was created to be automatic and transparent with as little code possible.  
                                This is done with a synchronized list of numbers located inside of the MochiCoins.inventory 
                                namespace.  To store, remove or update any value inside of this object, simply treat it 
                                as you would any other AS3 Object.
                            </p>

                            <div class="example">
                                <h4>Example:</h4>
    <blockquote class="code"><pre>
    // Create, or set the value of a property
    MochiCoins.inventory.grenades = 5;
    // Increment the number of grenades by 3
    MochiCoins.inventory.grenades += 3;
    // Finally, delete the grenades key from the object
    delete MochiCoins.inventory.grenades;

    // You can also access keys by string
    MochiCoins.inventory["grenades"] = 5;
    </pre></blockquote>
                            </div>

                            <p>
                                Modifying these values will start an automatic synchronization process with the server, 
                                automatically committing any changes you've made to the data after a short pooling period.
                            </p>

                            <p>
                                These property list is not immediately available for modification.  MochiInventory must 
                                first download the initial state of the object from our servers.  To accommodate the developer 
                                we have created a list of three events which should be used with your application.  
                            </p>

                            <dl>
                            <dt><strong>MochiInventory.READY</strong></dt>
                            <dd>Dispatched when MochiInventory has received it's initial synchronization and is ready for modifications.</dd>
                            </dl>

                            <dl>
                            <dt><strong>MochiInventory.WRITTEN</strong></dt>
                            <dd>Occurs when MochiInventory has been successfully written to the server.  This does not occur with every modification, as writes are deferred to reduce load on the server.  This is provided to notify you that a synchronization has recently taken place.</dd>
                            </dl>

                            <dl>
                                <dt><strong>MochiInventory.ERROR</strong> { type: xxx, error: xxx }</dt>
                                <dd>Occurs when an error has occurred with the MochiInventory API.  Type can be one of three different values:

                                <dl>
                                    <dt><strong>MochiInventory.IO_ERROR</strong> </dt>
                                    <dd>There was a network failure that prevented synchronization with the server</dd>
                                </dl>

                                <dl>
                                    <dt><strong>MochiInventory.NOT_READY</strong></dt>
                                    <dd>Attempted to modify the inventory object before initial data synchronization has occurred</dd>
                                </dl>
                                <dl>
                                    <dt><strong>MochiInventory.VALUE_ERROR</strong></dt>
                                    <dd>Attempted to store anything other than a number in the object</dd>
                                </dl>
                            </dd></dl>

                            <p>
                                All three of these basic events can be used to handle the basic status of the
                                MochiInventory system.
                            </p>

                            <div class="example">
                                <h4>Example:</h4>
    <blockquote class="code"><pre>                            
    function inventoryReady( event:Object ):void
    {
        // Inventory is ready to be modified
        MochiCoins.inventory.grenades = 5;    
    }

    function syncOccurred( event:Object ):void
    {
        trace("inventory written to server");
    }

    function handleError( error:Object ):void
    {
        switch( error.type )
        {
        case MochiInventory.IO_ERROR:
            trace("Network error:", error.error);
            break ;
        case MochiInventory.VALUE_ERROR:
            trace("Attempted to write non-Number value:", error.error);
            break ;
        case MochiInventory.NOT_READY:
            trace("Inventory not ready for modification:", error.error);
            break ;
        }
    }

    MochiInventory.addEventListener(MochiInventory.READY, inventoryReady);
    MochiInventory.addEventListener(MochiInventory.WRITTEN, syncOccurred);
    MochiInventory.addEventListener(MochiInventory.ERROR, handleError);
    </pre></blockquote>
                        </div>
                            

                            <p>
                                Finally, there is the purchase tracking that is built into MochiInventory.  MochiInventory 
                                automatically tracks purchases and will also work with the runtime property settings of 
                                various MochiCoins purchases to help you create things such as game-specific currency and consumable 
                                items.  When a purchase event is received by the MochiInventory API, the following things happen:
                            </p>

                            <p>
                                A key with the itemID of the purchase will automatically be created and/or incremented.  
                                For example, if a user purchases 5 of the item "0000000000000000", 
                                MochiCoins.inventory['0000000000000000'] will increment by 5.  You can increment or decrement this 
                                value at will, and the number will only be internally modified when the user makes additional purchases.
                            </p>

                            <p>
                                If the item is marked as consumable it will also increment the consumable key by a fixed amount per
                                purchase. This feature can be used to sell bundles of items such as $1000 of game-specific currency
                                or packs of 5 grenades.
                            </p>

                            <p>
                                To set the consumable values for an item, first, you must set the item as 'consumable' in the 'item type' 
                                section of the item settings for a store.
                            </p>

                           <img onclick="this.src = this.src;" src="img/item_type.png" width="541" height="234" />

                            <p>
                                Finally, you need to set the key, and the amount you want to increment this key by.  For example, 
                                if you wish to increment MochiInventory.inventory.grenades by 5 for each purchase of the item, you would set your settings like this example.
                            </p>

                            <img onclick="this.src = this.src;" src="img/consume_settings.png" width="542" height="332" />
                            <p>
                                You now have a pack of 5 consumable grenades available for purchase once you sync your store.<br/><br/>
                                Please note that this value is only tracked by the client side API, and the values themselves will 
                                not be reflected anywhere inside of the UI, and it is up to the developer to display the values of
                                the various properties.
                            </p>
                                
                            <p>
                                <strong>NOTE:</strong> If MochiInventory misses a purchase (due to communications failure, or 
                                other errors), MochiInventory will synchronize the missing purchases on the next game session.
                            </p>
                        </div>

                        </div>

                        <div class="section_2">
                            <a name="coins_sandbox"></a>
                            <h2>2.0 Sandbox Mode.</h2>
                            <p>
                            Sandbox Mode allows you to test the viewing and purchasing of items in your store without
                            publishing the changes to all players.  All changes to your store and items are only visible
                            in Sandbox Mode to Sandbox users until the changes are published.
                            </p>
                            <p>To test your store, items and purchasing in Sandbox Mode:</p>
                            <ol>
                                <li> Create or modify your store in your game's <i>Coins</i> tab.  Your changes will only be available to Sandbox users until they are published via the <i>Publish Changes</i> button.</li>
                                <li> In the <i>Sandbox Settings</i> menu on the right enter a list of Mochi Developer accounts to allow sandbox access.</li>
                                <li> Login to the Coins Login Widget as a Sandbox user by using your Mochi Developer username prepended with an '@'.  Your password is the same as your Mochi Developer password.</li>
                                <li> In Sandbox Mode you have a large amount (1,000,000) of coins for testing.</li>
                                <li> Clear all purchased items for Sandbox users with the <i>Clear Sandbox Inventory</i> button in the <i>Sandbox Settings</i> menu.</li>

                            </ol>
                        </div>
                        <div class="section_2">
                            <a name="coins_server"></a>
                            <h2>3.0 Server Validation</h2>
                            <p>
                            The Mochi Coins API has a very simple to use server to server API that lets you verify the identity and
                            inventory of a user for your game. This means that you don't have to trust the client, which prevents
                            cheating.
                            </p>
                            <p>
                            In the client's MochiSocial.LOGGED_IN event there is an "api_token" property. The API token will allow you
                            to make read-only server calls on behalf of that player. You will get a JSON response that summarizes who
                            the user is and what they own in your game.
                            </p>
                            <p>Example HTTP response from http://api.mochigames.com/coins/user-info/$$API_TOKEN</p>
    <blockquote class="code"><pre>
{
    "hasCoins": true, 
    "inventory": [
        {
            "count": 1, 
            "id": "2ecad5ea55fc7aba", 
            "properties": {
                "slug": "barkley"
            }, 
            "tags": [
                "dog",
                "small"
            ]
        }
    ], 
    "name": "name", 
    "uid": 1, 
    "userProperties": {
        "hitPoints": 120
    }
}
    </pre></blockquote>
                    
                    <p>Example PHP code:</p>
    <blockquote class="code"><pre>
$$handle = fopen("http://api.mochigames.com/coins/user-info/" . $$api_token, "rb");
$$contents = stream_get_contents($$handle);
fclose($$handle);
$$res = json_decode($$contents);

echo "User " . $$res->{'name'} . "\n";
foreach($$res->{'inventory'} as $$item) {
    echo "  owns " . $$item->{'count'} . " of item " . $$item->{'id'} . "\n";
}
    </pre></blockquote>

                    </div>
                    <!--! MOCHIADS -->
                    <div class="section_1">
                    <a name="MochiAds"></a>
                    <h1>Ads API Documentation</h1>

                       <p>This is a simple step-by-step guide to getting Mochi Ads API working with your Flash
                        game. Click the links below to skip to any part of this document.
                        The first two sections describe all that is required to get your ads running.</p>

                    <div class="section_2">
                        <h2><a name="Prerequisites:"></a>1.1 Prerequisites:</h2>

                        <p>
                            MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                        </p>

                        <p>Before you get started, make sure you have done the following:</p>

                        <ol>
                            <li> Sign up for a Mochi Developer account on www.mochimedia.com</li>
                            <li> Log in and add a new game to your account.</li>
                            <li> Download the MochiAPI include ZIP package.</li>
                            <li> Choose your code options and copy the Mochi Ads API in-game code.</li>
                        </ol>

                        <div class="download">
                            <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                        </div>
                    </div>

                    <div class="section_2">
                        <h2> <a name="The_MochiAds_Codes:"></a>1.2 The Mochi API Ad Codes:</h2>

                        <div class="figure" style="width: 240px;">
                            <img src="img/mochiads_zip_folders.jpg" width="212" height="199" />
                             <p><strong>Figure a:</strong> The MochiAPI ZIP package folder structure.</p>
                             <div class="spacer"></div>
                        </div>

                        <p>You need two things for Mochi Ads API to work properly in your game -- The mochi <em>include folder</em>, and the <em>in-game code</em>.</p>

                        <p>The <em>include folder</em> contains the ActionScript code that your game will
                        reference to display your ad. You will never need to edit this code.
                        You just need to make sure that it is in the proper location so that it is
                        imported or included when you publish or compile your game. You only need
                        to do this once for each game, no matter how many ads you show in the game.</p>

                        <p>The <em>in-game code</em> is the code you paste into your game to display the ad
                        at a specific point in the game. This may be placed in a specific frame on
                        the main timeline of your movie, or called when a specific event is called in
                        your game code. Depending on how you created your game,
                        where you place this code will differ. Just remember, when you make the
                        call to the Mochi Ads API, that's when the ad will show.</p>

                        <h3><a name="Include_File_Installation:"></a>Include Folder Installation:</h3>

                        <div class="figure" style="width: 320px;">
                            <!--! This unintuitive onclick has the effect of restarting the animated GIF -->
                               <img onclick="this.src = this.src;" src="img/copy_include.gif" width="300" height="230" />
                            <p><strong>Figure b:</strong> Copying the mochi folder to the directory of your .fla.<br />(Click image to restart animation)</p>
                            <div class="spacer"></div>
                        </div>

                        <p>The MochiAPI ZIP package contains the include code necessary for your
                        game. UnZIP the package to a location on your hard drive. If you browse to
                        that location, you will see a group of folders <cite>(fig.a)</cite>.</p>

                        <p>Make sure to read the README.TXT file for information regarding the latest
                        release of the MochiAPI file include.</p>

                        <p>Each folder in the package corresponds to a particular coding environment.
                        It's up to you to choose which one is best for you:</p>

                        <ul>
                            <li><strong>docs</strong>: MochiAPI usage documentation.</li>
                            <li><strong>examples</strong>: Examples using MochiAPI.</li>
                            <li><strong>mochi</strong>: MochiAPI include folder.</li>
                        </ul>

                        <p>Simply copy the <code>mochi</code> folder and paste it into the
                        location where you are publishing your game. You do not need to create a
                        special folder for the include <cite>(fig.b)</cite>.</p>

                        <p>These instructions also apply to the examples.  Simply copy the
                        <code>mochi</code> folder into the example project direct that you wish to use,
                        and publish to test.</p>

                        <h3><a name="Adding_the_In-game_Code:"></a>Adding the In-game Code: </h3>

                        <p>The <em>in-game code</em> is a one-line code snippet that you copy from the
                        Mochi Developer web site. This code is a method call that tells <code>MochiAPI</code> to launch your ad. You will paste
                        this code into your game in the place where you want the ad to appear.
                        Your code looks something like this:</p>

                        <p class="codetext">mochi.as2.MochiAd.showPreGameAd({id:&quot;xxxxxxxxxxxxxxxx&quot;,
                        res:&quot;360x240&quot;});</p>

                        <p><span style="color: #cc0000">NOTE:</span> In the 3.0 revision of the API, we changed namespaces for
                        our libraries to unify and organize our packages.  Now you must explicitly call the
                        API corresponding to your ActionScript version: <code>mochi.as2.*</code>  or
                        <code>mochi.as3.*</code> respectively.  For the purposes of this
                        documentation we will show examples specifying the ActionScript 2.0 MochiAPI.  Simply remove
                        <code>mochi.as2.</code> from the code samples, and add <code>import mochi.as3.*;</code>
                        to the beginning of your code block to use the ActionScript 3.0 MochiAPI.</p>

                        <p>There are three types of ads you can place in your game -- a <em>pre-game ad</em>,
                        an <em>inter-level ad</em> and a <em>Click-away ad</em>. Pre-game ads include a preloader bar that
                        grows as your game file is loaded from the web to the player's computer.
                        An inter-level ad is an ad that appears at some point during game-play.
                        The most convenient and unobtrusive time to show ads is usually between game
                        levels, hence the name inter-level ad.  Click-away ads are 300x250 ads that can be
                        placed anywhere you specify and will only disappear on a user-initiated action.</p>

                        <p>You can use the Mochi Developer web site to customize your code for the particular type
                        of ad and version of ActionScript you need.</p>

                        <p><span style="color: #cc0000">ACTIONSCRIPT 3 NOTE:</span> ActionScript 3 developers
                        will also notice that there is an additional parameter named <em>clip</em> which
                        passes a reference to the DisplayObject container for your ad to appear.
                        This is required, and by default this is set to root for pre-game and inter-level ads.
                        See below for more info regarding customizing this parameter.</p>

                        <h3><a name="Pregame_Code:"></a>Pre-game Ad:</h3>
                        <div class="figure">
                            <!--! This unintuitive onclick has the effect of restarting the animated GIF -->
                            <img onclick="this.src = this.src;" src="img/paste_pregame_code.gif" width="480" height="320" />
                            <p><strong>Figure c:</strong> Pasting the pre-game code into a game FLA.<br />(Click image to restart animation)</p>
                            <div class="spacer"></div>
                        </div>

                        <p>To add a <em>pre-game ad </em>with a preloader to your game, simply get the
                        appropriate in-game code from the Mochi Developer web site, and paste it into the main
                        timeline of your movie, in the place you've designated for a preloader <cite>(fig.c)</cite>.</p>

                        <p>If your game is ready, you can test your movie, and you should see the pre-game
                        ad appear as your movie loads. You may test your ads as much as you like
                        while you develop your game. Keep in mind that your ads will not earn
                        money until you complete your game profile which includes a URL to the completed
                        game. You may also upload your SWF file from the Game Settings page for free hosting.</p>

                        <h3><a name="Interlevel_Code:"></a>Inter-level Ad</h3>
                        <div class="figure">
                            <!--! This unintuitive onclick has the effect of restarting the animated GIF -->
                            <img onclick="this.src = this.src;" src="img/paste_interlevel_code.gif" width="480" height="320" />
                            <p><strong>Figure d:</strong> Pasting the inter-level code into a game FLA.<br />(Click image to restart animation)</p>
                            <div class="spacer"></div>
                        </div>

                        <p>To add an <em>inter-level ad</em> to your game, simply get the appropriate code
                        from the Mochi Developer web site, and paste it into the main timeline of your movie,
                        in the place you've designated for your inter-level screen <cite>(fig.d)</cite>.</p>

                        <p>Just like the pre-game ad, you can test your game and see the inter-level ads in action.</p>


                        <h3><a name="Clickaway_Code:"></a>Click-away ad</h3>

                        <p>To add a <em>Click-away ad</em> to your game, simply get the appropriate code
                        from the Mochi Developer web site.  Pass in the DisplayObject container / MovieClip which
                        will contain the Click-away ad in the <em>clip</em> parameter.  The upper left corner
                        of the 300x250 Click-away ad will be placed at the upper left corner of the DisplayObject
                        container / MovieClip you specify.  When you wish to stop displaying the Click-away ad
                        pass your <em>clip</em> to <code>MochiAd.unload()</code> depending on your respective ActionScript version
                        publish settings.</p>

                        <h3> Flash Player Security Settings: </h3>
                        <p>If you are testing locally outside of the Flash authoring environment and want
                        to be able to see ads, you will need to change the default local playback
                        security settings. In Flash, go to &quot;File -&gt; Publish Settings,&quot; then click on
                        the &quot;Flash&quot; tab. At the bottom, under &quot;Local Playback Security&quot;, choose &quot;Access
                        network only&quot; and then publish again. Keep in mind that if you are loading any
                        local data that it will no longer be accessible until you change your settings
                        back to &quot;Access local files only.&quot; These settings will not affect playback on
                        the web.</p>

                        <p>Alternatively, you may wish to add the location of your development files to
                        your global security settings in the <a href="http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html" title="Adobe Flash Player Settings Manager">Adobe
                        Flash Player Settings Manager</a>. This way, you can give all SWF files in this
                        location local-trusted access, allowing access to both local and remote data.</p>

                        <p>You will not need to do this if you are only testing your games in the Flash
                        authoring environment, although you will see Sandbox Violation warnings in the
                        Output panel. Warnings pertaining to MochiAPI can be safely ignored.</p>

                        <h3>Alternate In-game Code Placement </h3>
                        <p>Since there are many different ways to architect Flash games, it is very likely
                        that your game development setup is not the same as what you see above.
                        You may have nested MovieClips, or perhaps you are not using the timeline at
                        all. It is possible to place your in-game code in the timeline of a
                        MovieClip as well, and it will execute when the frame where you placed the code
                        is reached.</p>

                        <h3>And You're Done!</h3>
                        <p>That's all that is required to get MochiAPI Ads running in your game. When
                        you've completed your game and released it to the world, be sure to complete
                        your profile so that your game can be approved and you can start earning money
                        right away!</p>
                    </div>

                    <div class="section_2">
                        <h2><a name="Customizing_Your_Ad"></a>1.3 Customizing Your Ad</h2>

                        <p>It is possible to customize many of the visual elements and behaviors of your
                        Mochi Ads. The Mochi Ads API in-game code allows you to simply tailor
                        the display to suit your needs. Here's some of the things you can tweak:</p>

                        <ul>
                            <li><strong>MovieClip container:</strong> You can place your ad into any MovieClip on the stage, or into MovieClips you create with Actionscript.</li>
                            <li><strong>Timing:</strong> You can customize fade time of your ads.</li>
                            <li><strong>Colors:</strong> Change the colors of the ad preloader bar, background and outline.  You can also turn off the solid background.</li>
                            <li><strong>Event Handlers:</strong> You can assign custom functions to be called when ads start, load, and end.</li>
                        </ul>

                        <h3> The Mochi Ads API </h3>
                        <p>Your ads can be customized by sending special parameters via your in-game code.
                        Depending on whether you've chosen to display a pre-game or inter-level ad, your
                        options will be slightly different.</p>

                        <p>The in-game code is passed an object with keys and values to pass to the server.
                        The default code contains two keys -- id, the unique Mochi game ID, and
                        res, the height x width of your game. These parameters are required.</p>

                        <p class="codetext">mochi.as2.MochiAd.showPreGameAd({id:&quot;xxxxxxxxxxxxxxxx&quot;,
                        res:&quot;360x240&quot;});</p>

                        <p>You may add more key: value pairs to the object by separating them with commas.
                        You may add the following optional parameters to your object:</p>

                        <ul>
                            <li><strong>clip</strong><span class="vartype">:MovieClip</span> - a MovieClip reference in which to place the ad. Required for click-away ads or if you're using Actionscript 3.0. Otherwise the default is _root. <span class="default">(default: _root)</span></li>
                            <li><strong>no_bg</strong><span class="vartype">:Boolean</span> - setting to <em>true</em> allows you to disable the background entirely. <span class="default">(default: false)</span></li>
                        </ul>

                        <p>The following additional options apply to pre-game ads only:</p>

                        <ul>
                            <li><strong>color</strong><span class="vartype">:Number</span> - the color of the preloader bar as a number. <span class="default">(default: 0xFF8A00)</span></li>
                            <li><strong>background</strong><span class="vartype">:Number</span> - the inside color of the preloader bar as a number. <span class="default">(default: 0xFFFFC9)</span></li>
                            <li><strong>outline</strong><span class="vartype">:Number</span> - the outline color of the preloader bar as a number. <span class="default">(default: 0xD58B3C)</span></li>
                            <li><strong>no_progress_bar</strong><span class="vartype">:Boolean</span> - setting to <em>true</em> allows you to disable the preload progress bar. <span class="default">(default: false)</span></li>
                        </ul>

                        <p>You can find out the width and height of your ad when it loads. You can
                        use this information to create a custom frame around your ad that matches your
                        game.</p>

                         <ul>
                            <li><strong>ad_loaded</strong><span class="vartype">:Function</span> - ad_loaded is called just before an ad is displayed with the width and height of the ad.
                                <span class="default">(default: function(width:Number, height:Number):Void { }).</span></li>
                        </ul>

                        <p>You can also find out the progress of the preloader bar. You can
                        use this information to create your own preloader bar when used with the no_progress_bar option.</p>

                         <ul>
                            <li><strong>ad_progress</strong><span class="vartype">:Function</span> - ad_progress is called with the progress of the preloader bar.  The progress is a percent (represented from 0 to 100).
                                <span class="default">(default: function(percent:Number):Void { }).</span></li>
                        </ul>


                        <p>Here is an example of how the code might look if you were to add more options:</p>

                        <p class="codetext">mochi.as2.MochiAd.showPreGameAd({id:&quot;xxxxxxxxxxxxxxxx&quot;, res:&quot;360x240&quot;, clip: _root.myClip, no_bg: true, color: 0x006699, outline: 0xFFFFFF});</p>

                        <p>If you need to add many options, or define functions to handle ad events, you
                        may consider creating an object first, and then referencing that object when you
                        call the Mochi Ads API.</p>

<blockquote class="code"><pre>var myOptions:Object = {
    id: &quot;xxxxxxxxxxxxxxxx&quot;,
    res: &quot;360x240&quot;,
    clip: _root.myClip,
    color: 0x006699,
    background: 0x333333,
    outline: 0xFFFFFF,
    ad_loaded: function (width, height) { trace("ad loaded: " + width + "x" + height); }
    ad_progress: function (percent) { trace("preloader percent: " + percent); }
}
mochi.as2.MochiAd.showPreGameAd({myOptions});</pre></blockquote>

                        <p>There is also a tool on the Mochi Developer web site to customize the appearance of
                        your ad when you set up your in-game code. Often, this is easier than
                        editing the code by hand.</p>
                    </div>

                    <div class="section_2">
                        <h2><a name="Changing_Ad_Behaviors"></a>1.4 Changing Ad Behaviors</h2>

                        <p>The Mochi Ads API described above also allows you to assign your own event
                        handlers to be called by your ad. There are six events:</p>

                        <ul>
                            <li><strong>ad_started</strong><span class="vartype">:Function</span> - a function to call when the ad has started playing. <span class="default">(default: function ():Void { this.clip.stop() })</span></li>
                            <li><strong>ad_loaded</strong><span class="vartype">:Function</span> - a function to call just before an ad is displayed with the width and height of the ad. If it is called, it is called after ad_started.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 <span class="default">(default: function(width:Number, height:Number):Void { }).</span></li>
                            <li><strong>ad_finished</strong><span class="vartype">:Function</span> - a function to call when the ad has finished playing. <span class="default">(default: function ():Void { this.clip.play() })</span></li>
                            <li><strong>ad_failed</strong><span class="vartype">:Function</span> - a function to call if an ad can not be displayed, this is usually due to the user having ad blocking software installed or issues with retrieving the ad over the network. If it is called, then it is called before ad_finished. <span class="default">(default: function ():Void { })</span></li>
                            <li><strong>ad_skipped</strong><span class="vartype">:Function</span> - a function to call if the ad was skipped, this is usually due to frequency capping, or developer initiated domain filtering.  If it is called, then it is called before ad_finished. <span class="default">(default: function ():Void { })</span></li>
                            <li><strong>ad_progress</strong><span class="vartype">:Function</span> - a function to call when the progress of the preloader bar has changed.  The progress is a percent (represented from 0 to 100). <span class="default">(default: function(percent:Number):Void { }).</span></li>
                        </ul>

                        <p>When you assign custom functions to ad_started and ad_finished in your options object, your ad
                        will no longer stop and play the timeline. Instead, your custom functions will be called.</p>

<blockquote class="code"><pre>var myOptions:Object = {
    id: &quot;xxxxxxxxxxxxxxxx&quot;,
    res: &quot;360x240&quot;,
    clip: _root.myClip,
    ad_started: function ():Void { _global.game.pause(); },
    ad_finished: function ():Void { _global.game.resume(); }
}
mochi.as2.MochiAd.showPreGameAd({myOptions});</pre></blockquote>

                        <p>It is best to explicitly pass a function literal in your options object instead
                        of referencing a function in a separate class. That way, you do not need
                        to worry about losing scope or relying on the Delegate class. If you are
                        using ActionScript 3, though, you can pass a reference to your function without
                        losing scope.</p>

                        <p>Keep in mind that, if you define custom ad_started or ad_finished event handlers,
                        your timeline will no longer be stopped during the playback of your ad. So, if you still wish to
                        stop your timeline, you will need to be sure your event handler does this.</p>
                    </div>

                    <div class="section_2">
                        <h2><a name="MTASC_and_MXMLC"></a>1.5 MTASC and MXMLC</h2>

                        <p>For those developers who are developing in environments that don't use the Flash
                        IDE, the process for adding the Mochi Ads API will be slightly different. In order
                        to get your ads functioning in your game, you will need to:</p>

                        <ol>
                            <li> Make sure that the <code>mochi</code> folder is in your root project classpath.</li>
                            <li> You've added the in-game code in a method that is executed in an instantiated class in your game. </li>
                        </ol>
                    </div>

                    <div class="section_2">
                        <h2><a name="Flex"></a>1.6 Adobe Flex</h2>

                        <p>To use the Mochi Ads API as an Adobe Flex application's preloader, you will need to:</p>

                        <ol>
                            <li> Make sure that you use the <code>MochiPreloader.as</code> from the <i>examples/flex</i> folder from the MochiAPI ZIP package.</li>
                            <li> Make sure that the <code>mochi</code> folder and <code>MochiPreloader.as</code> are in your project classpath.</li>
                            <li> Tell your MXML application the preloader you want to use:
                                 <blockquote class="code"><pre>&lt;mx:Application xmlns:mx=&quot;http://www.adobe.com/2006/mxml&quot; preloader=&quot;MochiPreloader&quot;&gt;
&lt;/mx:Application&gt;</pre></blockquote>
                             </li>
                            <li> NOTE: With inter-level ads, the Mochi API is unable to tell your game when it has finished via the <code>MovieClip.stop()</code> and <code>MovieClip.start()</code> methods. You must use the <code>ad_started</code> and <code>ad_finished</code> callback methods in your game's options object (described in <a href="#Changing_Ad_Behaviors">Section 1.4</a>) to be notified when to start and stop your game.</li>
                        </ol>
                    </div>

                    <div class="section_2">
                        <h2><a name="AS3_Preloader"></a>1.7 ActionScript 3.0 Preloader</h2>

                                            <p>The <em>mxmlc</em> folder includes a preloader class (Preloader.as) that provides an example of how to properly compile a preloader into an AS3 SWF compiled with Adobe Flex mxmlc compiler.  For the preloader to function correctly, it must load first and execute before your base class and other SWF assets load.  In order for this to happen, the Preloader class is included on the first frame of your SWF and all of the other assets are included on the next frame.  The Preloader class contains a weak reference to your document class that it uses to instantiate your class after it completely loads your game.</p>

<blockquote class="code"><pre>// Change this class name to your main class
public static var MAIN_CLASS:String = "Test";
</pre></blockquote>

                                            <p>For Flex Builder, there is a makefile included in the example
                                            which tells the mxmlc compiler to include your Document Class in the
                                            second "frame" of your SWF so that the preloader will load first:</p>

<blockquote class="code"><pre>mxmlc \
               -default-frame-rate 31 \
               -default-size 550 400 \
               -use-network \
               -optimize=true \
               -output $@ \
               -frame=Test,Test \
               Preloader.as
</pre></blockquote>

                                            <p><em>Notice the compiler option '-frame=Test,Test'.</em></p>

                                            <p>If you are using FlashDevelop, you need to make sure you're passing "-frame Test, Test" to the mxmlc compiler,
                                            which you can set under <em>Compiler Options</em> in <em>Project Properties</em>. Don't forget to change 'Test'
                                            to the actual name of your base class.</p>

                    </div>


                    <div class="section_2">
                        <h2><a name="FlashDevelop"></a>1.8 Flash Develop</h2>

                        <p>Our example uses the <code>AS3 Empty Project Template</code> as it's basis.  Using our API within this framework is no more difficult
                        than that of a standard Flash IDE project.  Simply copy the <code>mochi</code> folder into the <code>src</code> folder created for your
                        project.  After you have done this, it is simply a matter of using that standard API calls</p>
                    </div>


                    <div class="section_2">
                        <h2><a name="More_Resources"></a>1.9 More Resources</h2>

                        <p>If you have questions about using the Mochi Ads API, you can view our <a href="https://www.mochimedia.com/support/dev_faq" >FAQs</a> or visit the <a href="https://www.mochimedia.com/community/">support forums</a>
                        for help. Also, if you have suggestions regarding this help document, we
                        encourage your feedback.</p>
                    </div>

                </div><!-- mochiads -->

                     <!--! MOCHISERVICES -->
                    <div class="section_1">
                        <a name="MochiServices"></a>
                        <h1>Scores API Documentation</h1>

                        <div class="section_2">
                            <a name="serv_ov"></a>
                            <h2>1.1 Overview</h2>
                            <p>
                                MochiServices is all Mochi APIs except for the Mochi Ads API. The API is dynamically loaded from Mochi servers and must be
                                initialized in either the first frame of your game or during Document Class initialization.
                            </p>
                        </div>

                        <div class="section_2">
                            <a name="serv_pre"></a>
                            <h2>1.2 Prerequisites</h2>
                            <p>
                                MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                            </p>

                            <h4>Installing the Mochi Scores API</h4>
                            <ol>
                                <li>Download and unzip the latest MochiAPI.</li>
                                <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                            </ol>

                            <p><span style="color: #cc0000">NOTE:</span> In the 3.0 revision of the API, we changed namespaces for
                            our libraries to unify and organize our packages.  Now you must explicitly call the
                            MochiAPI that is specific version: <code>mochi.as2.*</code>  or
                            <code>mochi.as3.*</code> respectively.  For the purposes of this
                            documentation we will show examples specifying the ActionScript 2.0 API.  Simply change
                            <code>mochi.as2.</code> from the code samples, and add <code>import mochi.as3.*;</code>
                            to the beginning of your code block to use the ActionScript 3.0 API.</p>

                            <div class="download">
                                <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                            </div>

                        </div>

                        <div class="section_2">
                            <a name="serv_api"></a>
                            <h2>1.3 Connecting to MochiServices</h2>

                            <div class="method">
                                <h3>connect</h3>
                                <div class="function">
                                    <div class="signature">
                                        connect(id:String, clip:Object, onError:Function):Void
                                    </div>

                                    <div class="description">
                                        <h4>Description:</h4>
                                        <p>
                                            Retrieves and initializes the MochiServices.swf from Mochi Ads servers. Any API calls executed prior to the complete download and initialization
                                            of the MochiServices.swf are queued and will be executed once the API is available
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters:</h4>
                                        <dl>
                                            <dt><strong>id</strong>:String</dt>
                                            <dd>Mochi game ID</dd>
                                            <dt><strong>clip</strong>:Object</dt>
                                            <dd>the MovieClip or Sprite in which to load the API (optional for all but AS3, defaults to _root).  In as3 the clip must be dynamic.</dd>
                                            <dt><strong>onError</strong>:Function</dt>
                                            <dd>
                                                This method will be invoked if MochiServices cannot connect to the server or any IO errors occur in any other API calls.
                                                onError handlers will receive status codes that describe the error.  The possible errors are:
                                                <ul>
                                                    <li>NotConnected &mdash; Services were unable to connect or attach to a clip in the current movie.</li>
                                                    <li>IOError &mdash; Services has connected but cannot transfer data to and from the server.</li>
                                                </ul>
                                            </dd>
                                        </dl>
                                    </div>




                                    <div class="example">
                                        <h4>AS2 Example:</h4>

<blockquote class="code"><pre>
mochi.as2.MochiServices.connect("xxx", root, onConnectError);

public function onConnectError(status:String):Void {
    <span class="comment">// handle error here...</span>
}
</pre></blockquote>

                                        <p>&hellip; where &lsquo;xxx&rsquo; is your Mochi game ID, in quotes.  Test your movie, and you should see the following text in your output panel:</p>

                                        <blockquote class="code trace">
                                            MochiServices Connecting&hellip;<br />
                                            Waiting for Mochi services to connect&hellip;<br />
                                            connected!
                                        </blockquote>

                                        <p>
                                            If you see the text above, then that means you have the "mochi" folder in the correct location, and have
                                            supplied MochiServices the correct Mochi game ID.  Keep in mind that you want to connect to MochiServices as early as
                                            possible in your game, and before you make any other API calls.  You only need to make this call once in the
                                            beginning of your game.
                                        </p>

                                        <h3>AS3 Requirement - The <em>clip</em> parameter</h3>
                                        <p>
                                            In ActionScript 3, the root of the Stage cannot be accessed globally.  If a Sprite or MovieClip does not have access to the root
                                            or to another Display Container that has been added to the display list, then it can not be shown visually on the screen.  For
                                            this reason, you must supply either the root of your stage or a reference to a Sprite or MovieClip that is a child of the stage
                                            to the clip parameter when you call MochiServices.connect.  Please note the clip passed must also be dynamic.
                                        </p>


                                    </div>
                                </div>
                            </div>

                        </div>

                        <div class="section_2">
                            <a name="MochiScores"></a>
                            <h1>Leaderboards</h1>

                            <div class="section_3">
                                <a name="score_ov"></a>
                                <h2>2.1 Overview</h2>
                                <p>
                                    Mochi Scores gives developers a simple drop-in solution to in-game scores. Developers can create any number of leaderboards
                                    they want for their game to track player scores. Scores are ranked and tracked
                                    in daily, weekly and monthly intervals.  Each game that you add to Mochi can have many leaderboards, but you must
                                    have at least one in order to use the Mochi Scores API.
                                </p>

                                <h3>Benefits of Mochi Scores:</h3>
                                <ul>
                                    <li>Use one line of code to show our complete in-game leaderboard.</li>
                                    <li>Create as many leaderboards as you want for each game.</li>
                                    <li>Track any kind of score &ndash; track by time or numbers and configure the sort order.</li>
                                    <li>Automatically remembers users name, and last score, and displays the users' country.</li>
                                    <li>Management tools let you delete player scores or ban them altogether.</li>
                                    <li>Encrypted communication from your game to Mochi Scores servers.</li>
                                    <li>Social network, Mochi Publisher and MochiGames integration.</li>
                                </ul>
                            </div>

                            <div class="section_3">
                                <a name="score_pre"></a>
                                <h2>2.2 Prerequisites</h2>
                                <p>
                                    MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                                </p>
                                <p>
                                    Before you get started, make sure you have done the following:
                                </p>
                                <ol>
                                    <li> Sign up for a Mochi Developer account on www.mochimedia.com</li>
                                    <li> Log in and add a new game to your account.</li>
                                    <li> Create a leaderboard for your game.</li>
                                    <li> Download the latest version of MochiAPI and copy the include folder to your .fla directory.</li>
                                    <li> Call <code>connect()</code> to initialize the Mochi Scores API.</li>
                                </ol>
                            </div>
                            <div class="clear"></div>

                            <div class="section_3">
                                <a name="Displaying_the_Leaderboard_Widget"></a>
                                <h2>2.3 Displaying the Leaderboard</h2>

                                <p>If you merely want to display the top scores for your game, then simply add the following script to your game:</p>

                                <blockquote class="code">
                                    <span class="comment">// stop the main timeline and display the leaderboard</span><br />
                                    mochi.as2.MochiScores.showLeaderboard({boardID: ”xxx”});
                                </blockquote>

                                <p>&hellip; where &lsquo;xxx&rsquo; is your board ID, in quotes.  If you&rsquo;ve already connected to MochiServices and set your board ID, then the leaderboard widget will call <strong>stop();</strong> to stop the timeline and then display itself.  Players cannot submit a high score this way &mdash; they can only see the scores.  This is handy if you want to allow players to see the high scores before they play the game.</p>

                                <p>By default, the showLeaderboard method will call <strong>stop();</strong> on the main timeline of your game, and then <strong>play();</strong> on the timeline once the leaderboard has been closed by the user.  This only occurs if you do not provide a container MovieClip for the leaderboard or your clip is the root of your movie.  If you wish to override this behavior, read about providing your own custom onDisplay and onClose handlers <a href="#Other_Leaderboard_Options">Section 2.8: Other Leaderboard Options</a>.</p>

                                <p>You will also notice that there is a preloader graphic that appears before the leaderboard displays.  This graphic will appear in the top left-hand corner of your game unless you provide a resolution in the leaderboard options.  If you provide a resolution, then the preloader graphic will appear centered in the area where the leaderboard will display.  You can also turn off the preloader graphic entirely by setting a variable in the leaderboard options.  Further information on options is detailed below.</p>

                                <p>In order to allow a player to submit a score after they&rsquo;ve played your game, then you would call the same method, but also supply an object containing their score, like so:</p>

                                <blockquote class="code">
                                    <span class="comment">// stop the main timeline and submit a score to the leaderboard</span><br />
                                    mochi.as2.MochiScores.showLeaderboard({boardID: ”xxx”, score: 128472});
                                </blockquote>

                                <p>&hellip; where 128472 is the player&rsquo;s actual score.  If you are tracking scores as times, like in a racing game, send the player score in milliseconds.  For instance, if the
                                player completed the game in 12.5 seconds, send the integer 12500.</p>


                                <p>When the leaderboard widget appears, there will be an input box where they can type in their username.  After they enter their name, they can then submit their score.</p>
                                <p>If you have your own registration system within your game, or wish to prevent the player from entering any name they wish, you can supply the username in code, like so:</p>

                                <blockquote class="code">
                                    <span class="comment">// stop the main timeline and submit a score and username to the leaderboard</span><br />
                                    mochi.as2.MochiScores.showLeaderboard({boardID: ”xxx”, score: 128472, name: “janedoe”});
                                </blockquote>

                                <p>&hellip; where &lsquo;janedoe&rsquo; is the username, in quotes.  This will show the leaderboard widget with the player name already entered, and not editable.</p>
                                <p>That&rsquo;s all you need to know to get started!  If you&rsquo;d like to do more advanced customization, read on.</p>
                            </div>
                            <div class="section_3">
                                <a name="Saving_Your_Board_ID"></a>
                                <h2>2.4 Saving Your Board ID</h2>

                                <p>If you do not wish to pass the board ID to the showLeaderboard call every time, you can save your board ID by adding the following code to your game:</p>

                                <blockquote class="code">
                                    <span class="comment">// set the board ID for all subsequent leaderboard calls</span><br />
                                    mochi.as2.MochiScores.setBoardID(”xxx”);
                                </blockquote>

                                <p>&hellip; where &lsquo;xxx&rsquo; is your board ID, in quotes.   This API method sets the board ID for future API calls, so you no longer need to pass the boardID parameter in your API calls.  You can always change this by calling this method with a different board ID.</p>
                            </div>
                            <div class="section_3">
                                <a name="Other_Leaderboard_Options"></a>
                                <h2>2.5 Other Leaderboard Options</h2>

                                <p>The <code>{}</code> in the showScores API call is an ActionScript object that is referred to as the options object.  These options change the way the leaderboard widget behaves.  You can enter as many supported optional parameters into this object as you wish.  Below is a list of all possible options.</p>

                                <h3>Basic Options:</h3>

                                <blockquote>
                                        score &mdash; the player's score to submit (integer, or time in milliseconds)<br />
                                        name &mdash; the player's name<br />
                                        boardID &mdash; board ID (overrides setBoardID)
                                </blockquote>

                                <h3>Callback Options:</h3>

                                <blockquote>
                                        onDisplay - the function to call when the GUI has displayed. default: function () { clip.stop(); }<br />
                                        onClose - the function to call when the GUI is finished or could not load. default: function () { clip.play(); }<br />
                                        onError - the function to call if the leaderboard cannot load.  default: onClose();
                                </blockquote>

                                <h3>Display Options:</h3>

                                <blockquote>
                                        res &mdash; the dimensions of the background behind your leaderboard. (i.e. &quot;500x400&quot;)<br />
                                        width &mdash; exact width for the leaderboard (optional).  The <em>height</em> must also be set.<br />
                                        height &mdash; exact height for the leaderboard (optional). The <em>width</em> must also be set.<br />
                                        preloaderDisplay &mdash; show a preloader graphic while the leaderboard loads.  The default is true.<br />
                                        numScores &mdash; maximum number of scores to display.  You can specify any number from 1 to 25, and the default is 10.  Changing this alters the height of the leaderboard.<br />
                                        hideDoneButton &mdash; set to true if you wish to hide the 'done' button and instead close the leaderboard in code by calling closeLeaderboard.<br />
                                        showTableRank &mdash; set to true if you wish to show the player's rank at the bottom of the table.<br />
                                        previewScores &mdash; set to true if you wish to display the top scores before the user submits their name and score.
                                        scoreMessage &mdash; allows the developer to change the messages used for the leaderboard.  This should
                                            be passed as an object in this format:
                                            { highscore: "Beat my highscore of $${highscore} in $${game}!",
                                                latestscore: "I just scored $${score} in $${game}!",
                                                gameinvite: "Come play $${game}!" }
                                </blockquote>

                                <h3>Replacement tokens used for customizing social link sharing</h3>
                                <blockquote>
                                    $${game} &mdash; Name of the game containing the leaderboard<br />
                                    $${board} &mdash; Name of the leaderboard<br />
                                    $${score} &mdash; Score user just submitted<br />
                                    $${highscore} &mdash; Highest score user has submitted<br />
                                </blockquote>
                                
                                <h3>Controlling Leaderboard Size:</h3>

                                <p>When you use the "res" option, your leaderboard will display centered in a background rectangle that matches those dimensions.  If you would like to specify the exact pixel dimensions of your leaderboard, you can supply two separate parameters, <em>width</em> and <em>height</em>.  If you use <em>width</em> and <em>height</em> but omit <em>res</em>, the background will disappear, and the leaderboard will move to 0,0 in _root or in the (optional) clip you specified in MochiServices.connect().  See the diagram below to see how the options work together:</p>

                                <img src="img/leaderboard_width_height_api.png" border="1" width="738" height="560" />

                            </div>
                            <div class="section_3">
                                <a name="The_MochiScores_API"></a>
                                <h2>2.6 API Reference</h2>

                                <p>This is the complete list of Mochi Scores API calls.  Most developers will only need to use connect, setBoardID, and showLeaderboard.  The other calls offer additional functionality to allow advanced developers to create their own custom leaderboards using the MochiServices back-end.</p>

                                <dl>
                                    <dt>mochi.as2.MochiScores.setBoardID(boardID:String):Void </dt>
                                        <dd>Sets the name of the mode to use for categorizing submitted and displayed scores.<br />
                                        @param boardID &mdash; The unique string name of the mode</dd>

                                    <dt>mochi.as2.MochiScores.showLeaderboard(options:Object):Void</dt>
                                        <dd>Displays the leaderboard GUI showing the current top scores.<br />
                                        @param options &mdash; optional parameters &lt;see: Leaderboard Options&gt;</dd>

                                    <dt>mochi.as2.MochiScores.closeLeaderboard():Void</dt>
                                        <dd>Closes the leaderboard GUI (Same as if the player clicked 'Done' on the leaderboard)</dd>

                                    <dt>mochi.as2.MochiScores.submit (score:Number, username:String, callbackObj:Object, callbackMethod:Object):Void</dt>
                                        <dd>Submits a score to the server. Will send a scores object to the callback &lt;see: Scores data format&gt;<br />
                                        @param name &mdash; the string name of the user.<br />
                                        @param score &mdash; the number representing a score. If the score is time, send it in milliseconds.<br />
                                        @param callbackObj &mdash; the object or class instance containing the callback method<br />
                                        @param callbackMethod &mdash; the string name of the method to call when the score has been sent</dd>

                                    <dt>mochi.as2.MochiScores.requestList (callbackObj:Object, callbackMethod:Object):Void</dt>
                                        <dd>Returns an array of at most 50 score objects. Will send a scores object to the callback &lt;see: <a href="#Scores_Data_Format">Scores data format</a>&gt;<br />
                                        @param callbackObj &mdash; the object or class instance containing the callback method<br />
                                        @param callbackMethod &mdash; the string name of the method to call when the score has been sent. default: &quot;onLoad&quot;</dd>

                                    <dt>mochi.as2.MochiScores.scoresArrayToObjects (scores:Object):Void</dt>
                                        <dd>Converts the array of arrays returned by requestList into an array of objects whose keys are derived from cols.<br />
                                        @param scores &mdash; the scores object returned to the requestList callback method</dd>

                                    <dt>mochi.as2.MochiScores.getPlayerInfo (callbackObj:Object, callbackMethod:Object):Void</dt>
                                        <dd>Retrieves all persistent player data that has been saved in a SharedObject.</dd>

                                </dl>
                            </div>
                            <div class="section_3">
                                <a name="Error_Handling"></a>
                                <h2>2.7 Error Handling</h2>

                                <p>All web services such as this require an internet connection in order to function properly.  Since it is possible that a player's internet connection
                                becomes unavailable during gameplay, it's possible that these services may not become available.  In order to handle this possibility, there are additional
                                error handlers you can pass to the services.</p>

                                  <p>
                                    The <code>mochi.as2.MochiServices.connect</code> method also includes the ability to pass an onError method.  You can also pass an optional onError handler showLeaderboard in the options object.  This will be invoked if the leaderboard
                                    cannot load for some reason.  By default, the onClose method is called if an error occurs.
                                </p>
                                <p>Other methods, such as requestList and submit, do not have onError handlers.  However, you can check the results that are returned to see if an error occurred.  Upon error,
                                the result object will return a variable named 'error' whose value will be true.  Also, a variable named 'errorCode' will return one of the above status codes.</p>

                            </div>
                            <div class="section_3">
                            <a name="Scores_Data_Format"></a>
                            <h2>2.8 Custom Leaderboards and Scores Data</h2>

                            <p>If you would like to create your own custom Leaderboard, you can use the Mochi Scores API to submit scores and retrieve up to 50 scores from your leaderboard.  To retrieve scores data, you must first set your board ID using the <strong>setBoardID</strong> method, and then call <strong>requestList</strong>, providing a callback method to receive the scores data object.</p>

                            <blockquote class="code">mochi.as2.MochiScores.setBoardID("xxxxxxxxxxxxxxxx");
                            <span class="comment"> // set the board ID to the leaderboard you wish to work with</span><br />
                            mochi.as2.MochiScores.requestList(this, "onScoresReceived");
                            <span class="comment"> // request the scores and send them to the onScoresReceived method in this object or class</span>
                            </blockquote>

                            <p>Your callback method should accept a single parameter of type <code>Object</code>.  This object will contain the scores object.  If there is an error, the object will contain a variable named <em>error</em> whose value is true, as well as a variable named <em>errorCode</em> which explains the error.</p>


<blockquote class="code"><pre>//
//

public function onScoresReceived (args:Object):Void {

    if (args.scores != null) {

        trace("Scores received!");

        var newScores:Object = mochi.as2.MochiScores.scoresArrayToObjects(args.scores);

    } else {

        if (args.error) {
            trace("Error: " + args.errorCode);
        }

    }

}
</pre></blockquote>


                            <p>If you are using the submit and requestList API calls to create your own custom Leaderboard, you will receive your scores data in the following format:</p>
<blockquote class="code trace">{
        now: 1197420828414.14,<br />
        places: { daily: 1, weekly: 2, monthly: 3 },<br />
        counts: { daily: 2, weekly: 4, monthly: 8 },<br />
        daily: { cols: [&quot;name&quot;, &quot;geo&quot;, &quot;score&quot;, &quot;timestamp&quot;], rows: [[&quot;george&quot;, &quot;us&quot;, 3333, 1197420828414.14], &hellip;]},<br />
        weekly: { cols: [&quot;name&quot;, &quot;geo&quot;, &quot;score&quot;, &quot;timestamp&quot;], rows: [[&quot;george&quot;, &quot;us&quot;, 3333, 1197420828414.14], &hellip;]},<br />
        monthly: { cols: [&quot;name&quot;, &quot;geo&quot;, &quot;score&quot;, &quot;timestamp&quot;], rows: [[&quot;george&quot;, &quot;us&quot;, 3333, 1197420828414.14], &hellip;]}<br />
    }</blockquote>
                            <p>This is an ActionScript object that contains four variables:</p>
                            <blockquote>
                                    now &mdash; the current server timestamp in milliseconds since the epoch<br />
                                    places &mdash; the percentile that the player's score achieved in each table<br />
                                    counts &mdash; the number of scores in each table<br />
                                    daily &mdash; scores for the daily table<br />
                                    weekly &mdash; scores for the weekly table<br />
                                    monthly &mdash; scores for the monthly table
                            </blockquote>
                            <p>The daily, weekly and monthly variables are objects that contain the following variables:</p>
                            <blockquote>
                                    cols &mdash; an array containing the column keys<br />
                                    rows &mdash; an array of row arrays.  each row array contains the values that correspond to each column key
                            </blockquote>

                            <p>You may also convert your scores from rows and columns to a list of objects by sending the scores data to <code>MochiScores.scoresArrayToObjects</code>.  This will return a new object where each row is an object with key-value pairs.  Shown below is an example of how the <em>daily</em> scores would be converted:</p>

                            <blockquote class="code trace">
                                daily { [{name: "george", geo: "us", score: 3333, timestamp, 11974208328414.14}, {name: "george", geo: "us", score: 3333, timestamp, 11974208328414.14}, &hellip;] }
                            </blockquote>

                        </div>
                        </div><!-- mochiscores -->

                        <!-- mochidigits -->
                        <div class="section_2">
                            <a name="MochiDigits"></a>
                            <h1>MochiDigits</h1>
                            <div class="section_3">
                                <a name="digits_ov"></a>
                                <h2>3.1 Overview</h2>
                                <p>
                                    MochiDigits provides a quick, and easy way for developers to encode their sensitive numbers in memory.  While there is no foolproof solution to
                                    the problem of hacking, this at least provides another layer of security for developers hoping to keep their scores from being modified with
                                    memory editing tools.
                                </p>
                            </div>
                            <div class="section_3">
                                <a name="digits_pre"></a>
                                <h2>3.2 Prerequisites</h2>

                                <h4>Installing the Mochi Scores API</h4>
                                <ol>
                                    <li>Download and unzip the latest MochiAPI.</li>
                                    <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                                </ol>

                                <div class="download">
                                    <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                                </div>
                            </div>
                            <div class="section_3">
                                <a name="digits_use"></a>
                                <h2>3.3 Usage</h2>
                                <p>
                                    Getting started using MochiDigits is simple.  MochiDigits operates like any other object, and can be modified using a set of easy to use functions
                                    or simply by directly altering a single property.
                                </p>

                                <blockquote class="code">
                                    import mochi.as2.MochiDigits;<br />
                                    <br />
                                    var score:MochiDigits;<br />
                                    score = new MochiDigits(0);
                                </blockquote>

                                <p>
                                    This creates a score object with the value "0".  Now you can alter the score simply by calling two easy to use functions
                                </p>

                                <dl>
                                    <dt>public function setValue(digit:Number):void</dt>
                                    <dd>Sets the value of a MochiDigits object to a specified number<br/>
                                    @param digit &mdash; The value to apply to the object</dd>

                                    <dt>public function addValue(inc:Number):void</dt>
                                    <dd>Increments the value of a MochiDigits object by a specified number<br/>
                                    @param digit &mdash; The value to increment the object by</dd>

                                    <dt>public function get value():Number<br/>
                                    public function set value(v:Number):void</dt>
                                    <dd>Property allowing direct access to the unencoded score</dd>
                                </dl>


                                <p>
                                    To use a real-world example, if you wished to say, give the player 100 points for grabbing an acorn, you would simply call addValue
                                </p>

                                <blockquote class="code">
                                    score.addValue(100);
                                </blockquote>

                                <p>
                                    It is just that easy.  Now, lets say the player has started a new level.  While you could create a new score object, it may be cleaner
                                    to simply set the value to zero.
                                </p>

                                <blockquote class="code">
                                    score.setValue(0);
                                </blockquote>

                                <p>
                                    Finally, you might be wondering how you can retrieve your score?  Simply using the .value property
                                </p>

                                <blockquote class="code">
                                    mochi.as2.MochiScores.showLeaderboard({boardID: ”xxx”, score: score.value});
                                </blockquote>

                                <p>
                                    You can use this property to do advanced tricks, like applying multipliers, or whatever else you can think of.  Just remember
                                    that so long as you are working on an unencrypted score, your data is vulnerable to attack.
                                </p>
                            </div>
                        </div>
                        <!-- mochidigits -->

                        <div class="section_2">
                            <a name="LinkTracking"></a>
                            <h1>Link Tracking API Documentation</h1>
                            <div class="section_1">

                                <a name="link_ov"></a>
                                <h2>1.1 Overview</h2>
                                <p>
                                    Mochi Link Tracking allows game developers can track all the traffic coming from their games. By using the Mochi Link Tracking
                                    method call you can get important stats for any link in your game. You can track as many in-game links as you want, and you
                                    can dynamically change the URL players are sent even after your game is spread across the internet.
                                </p>

                                <h3>Benefits of Link Tracking:</h3>
                                <ul>
                                    <li>Track as many links in your game as you want.</li>
                                    <li>Dynamically change the URL the link points to at any time.</li>
                                    <li>Includes enhanced pop-up blocking protection so your link works in as many situations as possible.</li>
                                    <li>Get valuable reporting telling you how much traffic your getting from each link.</li>
                                </ul>

                                <h3>Link Tracking works great for:</h3>
                                <ul>
                                    <li>Find out which link placements draw the most visitors.</li>
                                    <li>Learn about which hosts work best for driving traffic.</li>
                                    <li>Help determine the value of your game for sponsors with real traffic numbers.</li>
                                    <li>Sell timed sponsorship by dynamically changing the links to different sponsors on the fly.</li>
                                </ul>
                            </div>
                            <div class="section_1">
                                <a name="link_pre"></a>
                                <h2>1.2 Prerequisites</h2>

                                <p>
                                    MochiAPI is not compatible with versions prior to Flash Player 7, and is no longer compatible with ActionScript 1.0.
                                </p>

                                <h4>Installing the Mochi Ads API</h4>
                                <ol>
                                    <li>Download and unzip the latest MochiAPI.</li>
                                    <li>Copy the &ldquo;mochi&rdquo; folder and paste it into the root classpath of your game. Most often this is the same as the location of your game&rsquo;s FLA file.</li>
                                </ol>

                                <p><span style="color: #cc0000">NOTE:</span> In the 3.0 revision of the API, we changed namespaces for
                                our libraries to unify and organize our packages.  Now you must explicitly call the
                                MochiAPI that is specific version: <code>mochi.as2.*</code>  or
                                <code>mochi.as3.*</code> respectively.  For the purposes of this
                                documentation we will show examples specifying the ActionScript 2.0 API.  Simply change
                                <code>mochi.as2.</code> from the code samples, and add <code>import mochi.as3.*;</code>
                                to the beginning of your code block to use the ActionScript 3.0 API.</p>

                                <div class="download">
                                    <a href="http://www.mochimedia.com/dl/MochiAPI_v3_8.zip">MochiAPI 3.8</a>
                                </div>
                            </div>
                            <div class="section_1">
                                <a name="link_api"></a>
                                <h2>1.3 Link Tracking API</h2>

                                <div class="function">
                                    <h3>addLinkEvent()</h3>
                                    <div class="signature">
                                        <code>function addLinkEvent(url:String, backupUrl:String, container:DisplayObjectContainer, [callback:Function]):Void</code>
                                    </div>

                                    <div class="description">
                                        <h4>Description</h4>
                                        <p>
                                            Adds click event listening to a DisplayObjectContainer that directs the user to an external website.
                                        </p>
                                    </div>

                                    <div class="parameters">
                                        <h4>Parameters</h4>
                                        <dl>
                                            <dt><strong>url</strong>:String</dt>
                                            <dd>Redirect URL provided to you by Mochi when you create a new link.</dd>
                                            <dt><strong>backupUrl</strong>:String</dt>
                                            <dd>URL to fall back on if Mochi servers do not respond.</dd>
                                            <dt><strong>container</strong>:DisplayObjectContainer</dt>
                                            <dd>Reference to a valid DisplayObjectContainer (or MovieClip in AS2) to attach the click event to.</dd>
                                            <dt><strong>callback</strong>:Function</dt>
                                            <dd>Function to call when the click event occurs. No parameters are passed.</dd>
                                        </dl>
                                    </div>

                                    <div class="example">
                                        <h4>AS3 Example:</h4>
<blockquote class="code example"><pre>var container:Sprite = new Sprite(); <span class="comment">//If your using SimpleButton, you'll need a display container</span>
container.addChild(mySimpleButton); <span class="comment">//reference to your button</span>
mochi.as2.MochiServices.addLinkEvent(
    'http://link.mochiads.com/link/XXXXXXXXXXX',  <span class="comment">//Mochi provided URL</span>
    'http://mygamesite.com', <span class="comment">//Backup URL in case Mochi servers are unavailable</span>
    container, <span class="comment">//Sprite/Movie Clip to connect the click event to</span>
    onMenuClick <span class="comment">//Callback function</span>
);

<span class="comment">//...</span>

public function onMenuClick():Void {
    <span class="comment">// insert and callback code here</span>
}</pre></blockquote>
                                        <p class="note">
                                            <code>addLinkEvent</code> needs a reference to any DisplayObjectContainer. For example if you use a Sprite
                                            with <code>buttonMode = true</code> you can pass a reference to the Sprite itself. If you use a TextField of SimpleButton you'll
                                            need to add it to a containing Sprite.
                                        </p>
                                    </div>
                                </div><!--! end function -->

                            </div>
                        </div>
                    </div>
        </div>
    </div>
</body>
</html>
